Expand

import Expand from "@arcgis/core/widgets/Expand.js";

Inheritance:: Expand→Widget→Accessor

Since: ArcGIS Maps SDK for JavaScript 4.3

The Expand widget acts as a clickable button for displaying interactive content, most commonly other widgets.

If adding a Slider, HistogramRangeSlider, or TimeSlider as content to the Expand widget, the container or parent container of the widget must have a width set in css for it to render inside the Expand widget.

If setting the width on the slider's container, then set the slider.container as the content of the expand rather than the slider itself.

expand.content = slider.container

See also

Example

// LayerList
const layerList = new LayerList({
  container: document.createElement("div"),
  view: view
});
const layerListExpand = new Expand({
  expandIcon: "layers",  // see https://developers.arcgis.com/calcite-design-system/icons/
  // expandTooltip: "Expand LayerList", // optional, defaults to "Expand" for English locale
  view: view,
  content: layerList
});
view.ui.add(layerListExpand, "top-right");

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	`ExpandProperties`

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.

Property	Type	Class
`autoCollapse`	`boolean`
`closeOnEsc`	`boolean \| ((event: KeyboardEvent) => boolean)`
`collapseIcon`	`Icon["icon"]`
`collapseTooltip`	`string`
`container` inherited	`HTMLElement \| null \| undefined`	Widget
`content`	`ExpandContent`
`declaredClass` readonly inherited	`string`	Accessor
`destroyed` readonly inherited	`boolean`	Widget
`expanded`	`boolean`
`expandIcon`	`Icon["icon"]`
`expandTooltip`	`string`
`focusTrapDisabled`	`boolean`
`group`	`string \| null \| undefined`
`icon` inherited	`Icon["icon"] \| null \| undefined`	Widget
`iconNumber`	`number`
`id` inherited	`string`	Widget
`label`	`string`
`mode`	`"auto" \| "floating" \| "drawer"`
`placement`	`"auto" \| "auto-start" \| "auto-end" \| "top" \| "top-start" \| "top-end" \| "bottom" \| "bottom-start" \| "bottom-end" \| "right" \| "right-start" \| "right-end" \| "left" \| "left-start" \| "left-end" \| "leading-start" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start" \| null \| undefined`
`view`	`MapViewOrSceneView \| null \| undefined`
`viewModel`	`ExpandViewModel`
`visible` inherited	`boolean`	Widget

autoCollapse

Property

Type: boolean

Automatically collapses the expand widget instance when the view's viewpoint updates.

Default value: false

closeOnEsc

Property

Type: boolean | ((event: KeyboardEvent) => boolean)

When true, the Expand widget will close after the Escape key is pressed when the keyboard focus is within its content. This property can also be set to a function that returns a boolean, allowing for more customization for when to allow the Expand widget to be closed from the esc key.

Default value: true

Examples

let expand = new Expand({
   view: view,
   content: search,
   // widget will not be able to be closed from the ESC key
   closeOnEsc: false
});

let expand = new Expand({
   view: view,
   content: search,
   // widget will close on ESC when Search has no active menu
   closeOnEsc: function() {
     return search.activeMenu === "none"
   }
});

collapseIcon

autocast Property

Type: Icon["icon"]

Since: ArcGIS Maps SDK for JavaScript 4.27

Calcite icon used to style the Expand button when the content can be collapsed.

See also

Calcite Icon Search

Default value: "chevrons-right"

collapseTooltip

Property

Type: string

Tooltip to display to indicate Expand widget can be collapsed. If not provided, the widget will use "Collapse" (or equivalent in non-English locales).

Default value: ""

container

autocast inherited Property

Type: HTMLElement | null | undefined

Inherited from: Widget

The ID or node representing the DOM element containing the widget. This property can only be set once. The following examples are all valid use case when working with widgets.

Examples

// Create the HTML div element programmatically at runtime and set to the widget's container
const basemapGallery = new BasemapGallery({
  view: view,
  container: document.createElement("div")
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// Specify an already-defined HTML div element in the widget's container

const basemapGallery = new BasemapGallery({
  view: view,
  container: basemapGalleryDiv
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// HTML markup
<body>
  <div id="viewDiv"></div>
  <div id="basemapGalleryDiv"></div>
</body>

// Specify the widget while adding to the view's UI
const basemapGallery = new BasemapGallery({
  view: view
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

content

Property

Type: ExpandContent

The content to display within the expanded Expand widget.

If setting the width on the slider's container (rather than a parent container), then set the slider.container as the content of the expand rather than the slider itself.

expand.content = slider.container

Default value: ""

Examples

// A. specify content with a widget
   let searchWidget = new Search({
     view: view
   });

   let expand = new Expand({
     expandIcon: "search",
     view: view,
     content: searchWidget
   });
   view.ui.add(expand, "bottom-left");

// B. specify content with a string (of HTML)
   content: "Hi, I can have <input placeholder='HTML'/>!"

// C. specify content with a DOM node
   let node = domConstruct.create("div", {
     innerHTML: "I'm a real node!"
   });

   let expand = new Expand({
     expandIcon: "arrow-right",
     view: view,
     content: node
   });
   view.ui.add(expand, "top-right");

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.

destroyed

readonlyinherited Property

Type: boolean

Inherited from: Widget

When true, this property indicates whether the widget has been destroyed.

expanded

Property

Type: boolean

Indicates whether the widget is currently expanded or not.

Default value: false

expandIcon

autocast Property

Type: Icon["icon"]

Since: ArcGIS Maps SDK for JavaScript 4.27

Calcite icon used when the widget is collapsed. Will automatically use the content's icon if it has one.

See also

Calcite Icon Search

Default value: "chevrons-left"

expandTooltip

Property

Type: string

Tooltip to display to indicate Expand widget can be expanded. If not provided, the widget will use "Expand" (or equivalent in non-English locales).

Default value: ""

focusTrapDisabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.32

Disables focus trapping within the expand widget.

Default value: false

group

Property

Type: string | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.6

This value associates two or more Expand widget instances with each other, allowing one instance to auto collapse when another instance in the same group is expanded. For auto collapsing to take effect, all instances of the group must be included in the view's ui property.

For example, if you place multiple Expand instances in the top-left of the view's ui, you can assign them to a group called top-left. If one Expand instance is expanded and the user clicks on a different instance in the top-left group, then the first instance is collapsed, allowing the content of the second instance to be fully visible.

Example

let expand1 = new Expand({
  view: view,
  content: document.getElementById("bg-gallery"),
  expandIcon: "basemap",
  group: "bottom-right"
});
let expand2 = new Expand({
  view: view,
  content: document.getElementById("legend"),
  expandIcon: "key",
  group: "bottom-right"
});

view.ui.add([expand1, expand2], "bottom-right");

icon

inherited Property

Type: Icon["icon"] | null | undefined

Inherited from: Widget

Since: ArcGIS Maps SDK for JavaScript 4.27

Icon which represents the widget. It is typically used when the widget is controlled by another one (e.g. in the Expand widget).

See also

Calcite Icon Search

iconNumber

Property

Type: number

A number to display at the corner of the widget to indicate the number of, for example, open issues or unread notices.

Default value: 0

id

inherited Property

Type: string

Inherited from: Widget

The unique ID assigned to the widget when the widget is created. If not set by the developer, it will default to the container ID, or if that is not present then it will be automatically generated.

label

autocast Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 4.11

The widget's default label.

mode

Property

Type: "auto" | "floating" | "drawer"

Since: ArcGIS Maps SDK for JavaScript 4.7

The mode in which the widget displays. These modes are listed below.

mode	description
auto	This is the default mode. It is responsive to browser size changes and will update based on whether the widget is viewed in a desktop or mobile application.
floating	Use this mode if you wish to always display the widget as floating regardless of browser size.
drawer	Use this mode if you wish to always display the widget in a panel regardless of browser size.

Default value: "auto"

placement

Property

Type: "auto" | "auto-start" | "auto-end" | "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "right" | "right-start" | "right-end" | "left" | "left-start" | "left-end" | "leading-start" | "leading" | "leading-end" | "trailing-end" | "trailing" | "trailing-start" | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.30

The placement used by the calcite popover when the widget is expanded.

view

Property

Type: MapViewOrSceneView | null | undefined

A reference to the MapView or SceneView. Set this to link the widget to a specific view.

viewModel

autocast Property

Type: ExpandViewModel

The view model for this widget. This is a class that contains all the logic (properties and methods) that controls this widget's behavior. See the ExpandViewModel class to access all properties and methods on the widget.

visible

inherited Property

Type: boolean

Inherited from: Widget

Indicates whether the widget is visible.

If false, the widget will no longer be rendered in the web document. This may affect the layout of other elements or widgets in the document. For example, if this widget is the first of three widgets associated to the upper right hand corner of the DefaultUI, then the other widgets will reposition when this widget is made invisible. For more information, refer to the css display value of "none".

Default value: true

Example

// Hides the widget in the view
widget.visible = false;

Methods

Method	Signature	Class
`classes` inherited	`classes(...classNames: ((string \| null \| undefined) \| ((string[] \| Record<string, boolean>) \| null \| undefined) \| false \| null \| undefined)[]): string`	Widget
`collapse`	`collapse(): void`
`destroy` inherited	`destroy(): void`	Widget
`emit` inherited	`emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean`	EventedMixin
`expand`	`expand(): void`
`hasEventListener` inherited	`hasEventListener<Type extends EventNames<this>>(type: Type): boolean`	EventedMixin
`isFulfilled` inherited	`isFulfilled(): boolean`	EsriPromiseMixin
`isRejected` inherited	`isRejected(): boolean`	EsriPromiseMixin
`isResolved` inherited	`isResolved(): boolean`	EsriPromiseMixin
`on` inherited	`on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle`	EventedMixin
`postInitialize` inherited	`postInitialize(): void`	Widget
`render` inherited	`render(): any \| null`	Widget
`renderNow` inherited	`renderNow(): void`	Widget
`scheduleRender` inherited	`scheduleRender(): void`	Widget
`toggle`	`toggle(): void`
`when` inherited	`when<TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> \| null \| undefined, onRejected?: OnRejectedCallback<TResult2> \| null \| undefined): Promise<TResult1 \| TResult2>`	EsriPromiseMixin

classes

inherited Method

Signature: classes (...classNames: ((string | null | undefined) | ((string[] | Record<string, boolean>) | null | undefined) | false | null | undefined)[]): string

Inherited from: Widget

Since: ArcGIS Maps SDK for JavaScript 4.7

A utility method used for building the value for a widget's class property. This aids in simplifying css class setup.

Parameters

Parameter	Type	Description	Required
classNames	`((string \| null \| undefined) \| ((string[] \| Record<string, boolean>) \| null \| undefined) \| false \| null \| undefined)[]`	The class names.

Returns: string
The computed class name.

Example

// .tsx syntax showing how to set css classes while rendering the widget

render() {
  const dynamicClasses = {
    [css.flip]: this.flip,
    [css.primary]: this.primary
  };

  return (
    <div class={classes(css.root, css.mixin, dynamicClasses)} />
  );
}

collapse

Method

Signature: collapse (): void

Collapse the widget.

Returns: void

destroy

inherited Method

Signature: destroy (): void

Inherited from: Widget

Destroys the widget instance.

Returns: void

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

Parameter	Type	Description	Required
type	`Type`	The name of the event.
event	`this["@eventTypes"][Type]`	The event payload.

Returns: boolean
true if a listener was notified

Method

Signature: expand (): void

Expand the widget.

Returns: void

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

Parameter	Type	Description	Required
type	`Type`	The name of the event.

Returns: boolean
Returns true if the class supports the input event.

isFulfilled

inherited Method

Signature: isFulfilled (): boolean

Inherited from: EsriPromiseMixin

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected). If it is fulfilled, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been fulfilled (either resolved or rejected).

isRejected

inherited Method

Signature: isRejected (): boolean

Inherited from: EsriPromiseMixin

isRejected() may be used to verify if creating an instance of the class is rejected. If it is rejected, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been rejected.

isResolved

inherited Method

Signature: isResolved (): boolean

Inherited from: EsriPromiseMixin

isResolved() may be used to verify if creating an instance of the class is resolved. If it is resolved, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been resolved.

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

Parameter	Type	Description	Required
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).

Property	Type	Description
remove	Function	When 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);
});

postInitialize

inherited Method

Signature: postInitialize (): void

Inherited from: Widget

Executes after widget is ready for rendering.

Returns: void

render

inherited Method

Signature: render (): any | null

Inherited from: Widget

This method is implemented by subclasses for rendering.

Returns: any | null
The rendered virtual node.

renderNow

inherited Method

Signature: renderNow (): void

Inherited from: Widget

Renders widget to the DOM immediately.

Returns: void

scheduleRender

inherited Method

Signature: scheduleRender (): void

Inherited from: Widget

Schedules widget rendering. This method is useful for changes affecting the UI.

Returns: void

toggle

Method

Signature: toggle (): void

Toggle the widget by expanding it if it's collapsed, or collapsing it if it's expanded.

Returns: void

when

inherited Method

Signature: when <TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2>

Type parameters: <TResult1 = this, TResult2 = never>

Inherited from: EsriPromiseMixin

Since: ArcGIS Maps SDK for JavaScript 4.6

when() may be leveraged once an instance of the class is created. This method takes two input parameters: an onFulfilled function and an onRejected function. The onFulfilled executes when the instance of the class loads. The onRejected executes if the instance of the class fails to load.

Parameters

Parameter	Type	Description	Required
onFulfilled	`OnFulfilledCallback<this, TResult1> \| null \| undefined`	The function to call when the promise resolves.
onRejected	`OnRejectedCallback \| null \| undefined`	The function to execute when the promise fails.

Returns: Promise<TResult1 | TResult2>
Returns a new promise for the result of onFulfilled that may be used to chain additional functions.

Example

// Although this example uses MapView, any class instance that is a promise may use when() in the same way
let view = new MapView();
view.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

Type definitions

ExpandContent

Type definition

Type: string | HTMLElement | Widget | DomNodeOwner