UI

AMD: require(["esri/views/ui/UI"], (UI) => { /* code goes here */ });
ESM: import UI from "@arcgis/core/views/ui/UI.js";
Class: esri/views/ui/UI
Inheritance: UI Accessor
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

UI

Constructor
new UI(properties)
Parameter
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class
HTMLElement

The HTML Element that contains the view.

UI
String

The name of the class.

Accessor
Number

The height of the UI container.

UI
Object|Number

Defines the padding for the UI from the top, left, right, and bottom sides of the container or View.

UI
MapView|SceneView

The view associated with the UI components.

UI
Number

The width of the UI container.

UI

Property Details

container

Property
container HTMLElement

The HTML Element that contains the view.

See also

declaredClass

Inherited
Property
declaredClass Stringreadonly
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.7 Accessor since 4.0, declaredClass added at 4.7.

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

height

Property
height Numberreadonly

The height of the UI container.

padding

Property
padding Object|Number

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
view MapView|SceneView

The view associated with the UI components.

width

Property
width Numberreadonly

The width of the UI container.

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class

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

UI

Adds one or more handles which are to be tied to the lifecycle of the object.

Accessor

Removes all components from a given position.

UI
HTMLElement|Widget

Find a component by widget or DOM ID.

UI
Array<(Widget|HTMLElement)>

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

UI
Boolean

Returns true if a named group of handles exist.

Accessor

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

UI

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

UI

Removes a group of handles owned by the object.

Accessor

Method Details

add

Method
add(component, position)

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

Parameters
Specification

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.

Specification

The component to add to the UI. This can be a widget instance, HTML element, a string value representing a DOM node ID.

position String
optional

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.

Possible Values:"bottom-leading"|"bottom-left"|"bottom-right"|"bottom-trailing"|"top-leading"|"top-left"|"top-right"|"top-trailing"|"manual"

index Number
optional

The placement index of the component. This index shows where to place the component relative to other components. For example a value of 0 would place it topmost when position is top-*, leftmost for bottom-left and right most for bottom-right.

position String|Object
optional

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.

Specification
position String
optional

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.

Possible Values:"bottom-leading"|"bottom-left"|"bottom-right"|"bottom-trailing"|"top-leading"|"top-left"|"top-right"|"top-trailing"|"manual"

index Number
optional

The placement index of the component(s). This index shows where to place the component relative to other components. For example a value of 0 would place it topmost when position is top-*, leftmost for bottom-left and right most for bottom-right.

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
  }
]);

addHandles

Inherited
Method
addHandles(handleOrHandles, groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, addHandles added at 4.25.

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();
Parameters
handleOrHandles WatchHandle|WatchHandle[]

Handles marked for removal once the object is destroyed.

groupKey *
optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

empty

Method
empty(position)

Removes all components from a given position.

Parameter
position String
optional

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.

Possible Values:"bottom-leading"|"bottom-left"|"bottom-right"|"bottom-trailing"|"top-leading"|"top-left"|"top-right"|"top-trailing"|"manual"

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
find(id){HTMLElement|Widget}

Find a component by widget or DOM ID.

Parameter
id String

The component's ID.

Returns
Type Description
HTMLElement | Widget 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
getComponents(position){Array<(Widget|HTMLElement)>}
Since: ArcGIS Maps SDK for JavaScript 4.27 UI since 4.0, getComponents added at 4.27.

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

Parameter
optional

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

Returns
Type Description
Array<(Widget|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.

hasHandles

Inherited
Method
hasHandles(groupKey){Boolean}
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, hasHandles added at 4.25.

Returns true if a named group of handles exist.

Parameter
groupKey *
optional

A group key.

Returns
Type Description
Boolean Returns true if a named group of handles exist.
Example
// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

move

Method
move(component, position)

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

Parameters
Specification

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.

Specification

The component to move. This can be a widget instance, HTML element, a string value representing a DOM node ID.

position String
optional

The destination position. The component will be placed in the UI container when not provided. 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.

Possible Values:"bottom-leading"|"bottom-left"|"bottom-right"|"bottom-trailing"|"top-leading"|"top-left"|"top-right"|"top-trailing"|"manual"

index Number
optional

The placement index of the component. This index shows where to place the component relative to other components. For example a value of 0 would place it topmost when position is top-*, leftmost for bottom-left and right most for bottom-right.

position String|Object
optional

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

Specification
position String
optional

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.

Possible Values:"bottom-leading"|"bottom-left"|"bottom-right"|"bottom-trailing"|"top-leading"|"top-left"|"top-right"|"top-trailing"|"manual"

index Number
optional

The placement index of the component(s). This index shows where to place the component relative to other components. For example a value of 0 would place it topmost when position is top-*, leftmost for bottom-left and right most for bottom-right.

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});

remove

Method
remove(component)

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

Parameter

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.

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" ]);

removeHandles

Inherited
Method
removeHandles(groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, removeHandles added at 4.25.

Removes a group of handles owned by the object.

Parameter
groupKey *
optional

A group key or an array or collection of group keys to remove.

Example
obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

Type Definitions

UIPosition

Type Definition
UIPosition String

The UI position of an element in the view.

Possible Values:"bottom-leading"|"bottom-left"|"bottom-right"|"bottom-trailing"|"top-leading"|"top-left"|"top-right"|"top-trailing"|"manual"

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.