Skip to content
import UI from "@arcgis/core/views/ui/UI.js";
Inheritance:
UIAccessor
Subclasses:
DefaultUI
Since
ArcGIS Maps SDK for JavaScript 4.0

This class provides a simple interface for adding, moving and removing components from a view's user interface (UI). In most cases, you will work with the view's DefaultUI which places default widgets, such as Zoom and Attribution in the View.

The UI class provides the API for easily placing HTML elements and widgets within the view. See DefaultUI for details on working with this class.

See also

Constructors

Constructor

Constructor
Parameters
ParameterTypeDescriptionRequired
properties
See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.
PropertyTypeClass
declaredClass
readonly inherited
height
readonly
any
width
readonly

container

Property
Type
HTMLElement | null | undefined

The HTML Element that contains the view.

See also

declaredClass

readonlyinherited Property
Type
string
Inherited from: Accessor
Since
ArcGIS Maps SDK for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

height

readonly Property
Type
number

The height of the UI container.

padding

autocast Property
Type
any

Defines the padding for the UI from the top, left, right, and bottom sides of the container or View. If the value is a number, it will be used to pad all sides of the container.

Default value
{ left: 15, top: 15, right: 15, bottom: 15 }
Example
// Setting a single number to this property
ui.padding = 0;
// is the same as setting it on all properties of the object
ui.padding = { top: 0, left: 0, right: 0, bottom: 0 };

view

Property
Type
MapView | SceneView

The view associated with the UI components.

width

readonly Property
Type
number

The width of the UI container.

Methods

MethodSignatureClass
add
add(component: Widget | HTMLElement | string | any[] | ComponentCompatible, position?: string | UIPosition | Options): void
emit
inherited
emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
empty(position?: UIPosition): void
find(id: string): Widget | HTMLElement | null | undefined
getComponents(position?: UIPosition | UIPosition[]): (Widget<any> | HTMLElement)[]
hasEventListener
inherited
hasEventListener<Type extends EventNames<this>>(type: Type): boolean
move(component: ComponentCompatible | ComponentCompatible[], position?: UIPosition | MoveOptions): void
on
inherited
on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
remove(component: ComponentCompatible | ComponentCompatible[]): void

add

Method
Signature
add (component: Widget | HTMLElement | string | any[] | ComponentCompatible, position?: string | UIPosition | Options): void

Adds one or more HTML component(s) or widgets to the UI.

Parameters
ParameterTypeDescriptionRequired
component

The component(s) to add to the UI. This can be a widget instance, HTML element, a string value representing a DOM node ID, or an array containing a combination of any of those types. See the example snippets below for code examples. Alternatively, you can pass an array of objects with the following specification.

position

The position in the view at which to add the component. If not specified, manual is used by default. Using manual allows you to place the component in a container where you can position it anywhere using css. For the other possible values, "top", "bottom", "left", and "right" are consistent placements. The "leading" and "trailing" values depend on whether the browser is using right-to-left (RTL) or left-to-right (LTR). For LTR, "leading" is left and "trailing" is right. For RTL, "leading" is right and "trailing" is left.

Returns
void
Examples
let toggle = new BasemapToggle({
view: view,
nextBasemap: "hybrid"
});
// Adds an instance of BasemapToggle widget to the
// top right of the view's container.
view.ui.add(toggle, "top-right");
// Adds multiple widgets to the top right of the view
view.ui.add([ compass, toggle ], "top-leading");
// Adds multiple components of different types to the bottom left of the view
view.ui.add([ searchWidget, "infoDiv" ], "bottom-left");
// Adds multiple components of various types to different view positions
view.ui.add([
{
component: compassWidget,
position: "top-left",
index: 0
}, {
component: "infoDiv",
position: "bottom-trailing"
}, {
component: searchWidget,
position: "top-right",
index: 0
}, {
component: legendWidgetDomNode,
position: "top-right",
index: 1
}
]);

emit

inherited Method
Signature
emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
Type parameters
<Type extends EventNames<this>>
Inherited from: EventedMixin
Since
ArcGIS Maps SDK for JavaScript 4.5

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters
ParameterTypeDescriptionRequired
type
Type

The name of the event.

event
this["@eventTypes"][Type]

The event payload.

Returns
boolean

true if a listener was notified

empty

Method
Signature
empty (position?: UIPosition): void

Removes all components from a given position.

Parameters
ParameterTypeDescriptionRequired
position

The position in the view at which to add the component. If not specified, manual is used by default. Using manual allows you to place the component in a container where you can position it anywhere using css. For the other possible values, "top", "bottom", "left", and "right" are consistent placements. The "leading" and "trailing" values depend on whether the browser is using right-to-left (RTL) or left-to-right (LTR). For LTR, "leading" is left and "trailing" is right. For RTL, "leading" is right and "trailing" is left.

Returns
void
Example
// Removes all of the elements in the top-left of the view's container
// including the default widgets zoom and compass (if working in SceneView)
view.ui.empty("top-left");

find

Method
Signature
find (id: string): Widget | HTMLElement | null | undefined

Find a component by widget or DOM ID.

Parameters
ParameterTypeDescriptionRequired
id

The component's ID.

Returns
Widget | HTMLElement | null | undefined

Returns the Widget or HTMLElement if the id is found, otherwise returns null.

Example
let compassWidget = new Compass({
view: view,
id: "myCompassWidget" // set an id to get the widget with find
});
// Add the Compass widget to the top left corner of the view
view.ui.add(compassWidget, "top-left");
// Find the Widget with the specified ID
let compassWidgetFind = view.ui.find("myCompassWidget"))

getComponents

Method
Signature
getComponents (position?: UIPosition | UIPosition[]): (Widget<any> | HTMLElement)[]
Since
ArcGIS Maps SDK for JavaScript 4.27

Returns all widgets and/or HTML elements in the view, or only components at specified positions in the view.

Parameters
ParameterTypeDescriptionRequired
position

The position or array of positions from which to fetch the components. If not specified, all components will be returned from the View.

Returns
(Widget<any> | HTMLElement)[]

Returns an array of Widgets and/or HTML elements in the View.

Examples
// Display the number of components added to MapView by default.
const view = new MapView({
map,
container: "viewDiv",
zoom: 4,
center: [-100, 35]
});
await view.when();
const components = view.ui.getComponents();
console.log(`There are ${components.length} components added to MapView.`); // There are 4 components added to MapView.
// Display the label of the first manually placed widget in SceneView.
const view = new SceneView({
map,
container: "viewDiv",
zoom: 4,
center: [-100, 35]
});
await view.when();
console.log("Widget label is: ${view.ui.getComponents("manual")[0].label}.`); // Widget label is: Attribution.
// Display how many components (i.e. widgets or HTMLElements) are placed in the top-left corner of the View.
const view = new MapView({
map,
container: "viewDiv",
zoom: 4,
center: [-100, 35]
});
await view.when();
const components = view.ui.getComponents("top-left");
console.log(`There is/are ${components.length} component(s) located in MapView's top-left corner.`);
// There is/are 1 component(s) located in MapView's top-left corner.

hasEventListener

inherited Method
Signature
hasEventListener <Type extends EventNames<this>>(type: Type): boolean
Type parameters
<Type extends EventNames<this>>
Inherited from: EventedMixin

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameters
ParameterTypeDescriptionRequired
type
Type

The name of the event.

Returns
boolean

Returns true if the class supports the input event.

move

Method
Signature
move (component: ComponentCompatible | ComponentCompatible[], position?: UIPosition | MoveOptions): void

Moves one or more UI component(s) to the specified position.

Parameters
ParameterTypeDescriptionRequired
component

The component(s) to move. This value can be a widget instance, HTML element, a string value representing a DOM node ID, or an array containing a combination of any of those types. See the example snippets below for code examples. Alternatively, you can pass an array of objects with the following specification.

position

The destination position. The component will be placed in the UI container when not provided.

Returns
void
Examples
// Moves the BasemapToggle widget from the view if added.
// See the example for add() for more context
view.ui.move(toggle, "bottom-leading");
// Moves the default zoom widget to the bottom left corner of the view's container
view.ui.move("zoom", "bottom-left");
// Moves multiple widgets to the bottom right of the view's UI
view.ui.move([ compass, toggle, "zoom" ], "bottom-right");
// Moves the legend to the topmost position in the top-right corner of the view's UI.
view.ui.move({component: legend, position: "top-right", index: 0});

on

inherited Method
Signature
on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
Type parameters
<Type extends EventNames<this>>
Inherited from: EventedMixin

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters
ParameterTypeDescriptionRequired
type
Type

An event or an array of events to listen for.

listener
EventedCallback<this["@eventTypes"][Type]>

The function to call when the event fires.

Returns
ResourceHandle

Returns an event handler with a remove() method that should be called to stop listening for the event(s).

PropertyTypeDescription
removeFunctionWhen called, removes the listener from the event.
Example
view.on("click", function(event){
// event is the event handle returned after the event fires.
console.log(event.mapPoint);
});

remove

Method
Signature
remove (component: ComponentCompatible | ComponentCompatible[]): void

Removes one or more HTML component(s) or widgets from the UI.

Parameters
ParameterTypeDescriptionRequired
component

The component(s) to remove from the UI. This can be a widget instance, HTML element, a string value representing a DOM node ID, or an array containing a combination of any of those types. See the example snippets below for code examples.

Returns
void
Examples
// Removes the BasemapToggle widget from the view if added.
// See the example for add() for more context
view.ui.remove(toggle);
// Removes the default zoom widget from the view's container
view.ui.remove("zoom");
// Removes multiple widgets from the view's UI
view.ui.remove([ compass, toggle, "zoom" ]);