arcgis-bookmarks | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-bookmarks";

Inheritance:: ArcgisBookmarks→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Bookmarks component allows end users to quickly navigate to a particular area of interest. It displays a list of bookmarks, which are typically defined inside the WebMap.

Each bookmark may contain the following properties: name, thumbnail, viewpoint (defines rotation, scale, and target geometry), and timeExtent. When a bookmark with a timeExtent is selected, the arcgis-map.timeExtent of the Map will be set to the timeExtent of the selected bookmark. To disable time capability in the Bookmarks component, set timeDisabled to true.

The Bookmarks component can be used to create, edit, reorder, and delete bookmarks. To enable these features, set the following properties to true: showAddBookmarkButton, showEditBookmarkButton, and dragEnabled.

Note: Bookmarks are supported in a 3D Scene only if they come from a WebMap or are provided manually from bookmarks. Presentation provides a similar experience for WebScenes.

See also

Sample - Bookmarks component

Demo

Properties

Property	Attribute	Type
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`bookmarks`	`bookmarks`	`Collection<Bookmark>`
`closed` reflected	`closed`	`boolean`
`defaultCreateOptions`		`BookmarkOptions`
`defaultEditOptions`		`BookmarkOptions`
`disabled`	`disabled`	`boolean`
`dragEnabled`	`drag-enabled`	`boolean`
`filterPlaceholder`	`filter-placeholder`	`string`
`filterText`	`filter-text`	`string`
`goToOverride`		`GoToOverride \| undefined`
`headingLevel`	`heading-level`	`HeadingLevel`
`hideThumbnail`	`hide-thumbnail`	`boolean`
`hideTime`	`hide-time`	`boolean`
`icon`	`icon`	`IconName`
`label`	`label`	`string \| undefined`
`messageOverrides`		`Record<string, unknown> \| undefined`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`showAddBookmarkButton`	`show-add-bookmark-button`	`boolean`
`showCloseButton`	`show-close-button`	`boolean`
`showCollapseButton`	`show-collapse-button`	`boolean`
`showEditBookmarkButton`	`show-edit-bookmark-button`	`boolean`
`showFilter`	`show-filter`	`boolean`
`showHeading`	`show-heading`	`boolean`
`state` readonly		`BookmarksState`
`timeDisabled`	`time-disabled`	`boolean`
`view`		`MapView \| SceneView \| undefined`

autoDestroyDisabled

Property

Type: boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute: auto-destroy-disabled
Default value: false

bookmarks

autocast Property

Type: Collection<Bookmark>

A collection of Bookmarks. These are typically defined inside of a WebMap, but can also be defined manually, as shown in the code snippet below.

Attribute: bookmarks

Example

const bookmarksElement = document.querySelector("arcgis-bookmarks");
// define bookmarks manually
bookmarksElement.bookmarks = [
  new Bookmark({
    name: "Angeles National Forest",
    viewpoint: {
      targetGeometry: {
        type: "extent",
        spatialReference: {
          wkid: 102100
        },
        xmin: -13139131.948889678,
        ymin: 4047767.23531948,
        xmax: -13092887.54677721,
        ymax: 4090610.189673263
      }
    }
  }),
  new Bookmark({
    name: "Crystal Lake",
    viewpoint: {
      targetGeometry: {
        type: "extent",
        spatialReference: {
          wkid: 102100
        },
        xmin: -13125852.551697943,
        ymin: 4066904.1101411926,
        xmax: -13114291.451169826,
        ymax: 4077614.8487296384
      },
      rotation: 90
    }
  })
];

closed

reflected Property

Type: boolean

Indicates whether a component is closed. When true, the component will be hidden.

Attribute: closed
Default value: false

defaultCreateOptions

autocast Property

Type: BookmarkOptions

Specifies how new bookmarks will be created if showAddBookmarkButton is set to true. Can be used to enable or disable taking screenshots or capturing the bookmark's viewpoint based on the current view when a bookmark is created.

Example

const bookmarksElement = document.querySelector("arcgis-bookmarks");
bookmarksElement.showAddBookmarkButton = true;
bookmarksElement.defaultCreateOptions = {
  // whenever a new bookmark is created, a 100x100 px
  // screenshot of the view will be taken and the rotation, scale, and extent
  // of the view will not be set as the viewpoint of the new bookmark
  takeScreenshot: true,
  captureViewpoint: false,
  captureTimeExtent: false, // the time extent will not be saved in the bookmark
  screenshotSettings: {
    width: 100,
    height: 100
  }
};

defaultEditOptions

autocast Property

Type: BookmarkOptions

Specifies how bookmarks will be edited, if showEditBookmarkButton is set to true. Can be used to enable or disable taking screenshots or capturing the bookmark's viewpoint based on the current view when a bookmark is edited.

disabled

Property

Type: boolean

When true, the component is visually withdrawn and cannot receive user interaction.

Attribute: disabled
Default value: false

dragEnabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.29

Indicates if a Bookmark is able to be dragged in order to update its position in the list.

Attribute: drag-enabled
Default value: false

filterPlaceholder

Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 4.29

Defines the text used as a placeholder when showFilter is set to true.

Attribute: filter-placeholder
Default value: ""

filterText

Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 4.29

Defines the text used to filter the bookmarks when showFilter is set to true.

Attribute: filter-text
Default value: ""

goToOverride

Property

Type: GoToOverride | undefined

Since: ArcGIS Maps SDK for JavaScript 4.33

This function provides the ability to override either the arcgis-map.goTo() or arcgis-scene.goTo() methods.

Example

component.goToOverride = function(view, goToParams) {
  goToParams.options = {
    duration: updatedDuration
  };
  return view.goTo(goToParams.target, goToParams.options);
};

headingLevel

Property

Type: HeadingLevel

Since: ArcGIS Maps SDK for JavaScript 4.34

Indicates the heading level to use for the message "No bookmarks" when no bookmarks are available. By default, this message is rendered as a level 2 heading (e.g. <h2>No bookmarks</h2>). Depending on the component's placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.

See also

Heading Elements

Attribute: heading-level
Default value: 2

Example

// "No bookmarks" will render as an <h3>
bookmarksElement.headingLevel = 3;

hideThumbnail

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

Indicates whether the thumbnail associated with the bookmark is hidden.

Attribute: hide-thumbnail
Default value: false

hideTime

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

Indicates whether the time (h:m:s) displayed next to the date is hidden if the bookmark has a time extent defined.

Attribute: hide-time
Default value: false

icon

Property

Type: IconName

Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).

See also

Calcite Icons

Attribute: icon
Default value: "bookmark"

label

Property

Type: string | undefined

The component's default label.

Attribute: label

messageOverrides

Property

Type: Record<string, unknown> | undefined

Since: ArcGIS Maps SDK for JavaScript 4.34

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

referenceElement

Property

Type: ArcgisReferenceElement | string | undefined

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also

Associate components with a Map or Scene component

Attribute: reference-element

showAddBookmarkButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

Indicates whether to display the button to add a new bookmark.

Attribute: show-add-bookmark-button
Default value: false

showCloseButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

Indicates whether to display the close button.

Attribute: show-close-button
Default value: false

showCollapseButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

Indicates whether to display the collapse button.

Attribute: show-collapse-button
Default value: false

showEditBookmarkButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

Indicates whether to display the button to edit a bookmark.

Attribute: show-edit-bookmark-button
Default value: false

showFilter

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

Indicates whether to display the bookmark filter.

Attribute: show-filter
Default value: false

showHeading

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.30

Indicates whether to display the heading.

Attribute: show-heading
Default value: false

state

readonly Property

Type: BookmarksState

The current state of the component.

Default value: "ready"

timeDisabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.34

Indicates whether to disable the time capability of the Bookmarks component.

Attribute: time-disabled
Default value: false

view

Property

Type: MapView | SceneView | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-bookmarks component will be associated with a map or scene component rather than using the view property.

Methods

Method	Signature
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`destroy`	`destroy(): Promise<void>`
`goTo`	`goTo(bookmark: Bookmark): Promise<void>`

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: PublicLitElement

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisBookmarks = document.querySelector("arcgis-bookmarks");
document.body.append(arcgisBookmarks);
await arcgisBookmarks.componentOnReady();
console.log("arcgis-bookmarks is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

goTo

Method

Signature: goTo (bookmark: Bookmark): Promise<void>

Since: ArcGIS Maps SDK for JavaScript 4.34

Zoom to a specific bookmark.

Parameters

Parameter	Type	Description	Required
bookmark	`Bookmark`

Returns: Promise<void>

Events

Name	Type
`arcgisBookmarkEdit`	CustomEvent<BookmarkEditEvent>
`arcgisBookmarkSelect`	CustomEvent<BookmarkSelectEvent>
`arcgisClose`	CustomEvent<void>
`arcgisPropertyChange`	CustomEvent<{ name: "state"; }>
`arcgisReady`	CustomEvent<void>

arcgisBookmarkEdit

Event

arcgisBookmarkEdit: CustomEvent<BookmarkEditEvent>

Since: ArcGIS Maps SDK for JavaScript 4.34

Fires when a Bookmark is edited.

Example

// once an edit has been made, enable the "Save Webmap" button
//    to allow the user to save their changes
bookmarksElement.addEventListener("arcgisBookmarkEdit", (event) => {
   saveBtn.disabled = false;
});

arcgisBookmarkSelect

Event

arcgisBookmarkSelect: CustomEvent<BookmarkSelectEvent>

Since: ArcGIS Maps SDK for JavaScript 4.34

Fires when a Bookmark is selected.

Example

<arcgis-expand expanded>
 <arcgis-bookmarks></arcgis-bookmarks>
</arcgis-expand>

<script>
  const bookmarksElement = document.querySelector("arcgis-bookmarks");
  const expandElement = document.querySelector("arcgis-expand");

  // collapses the associated Expand component
  // when a bookmark is selected
  bookmarksElement.addEventListener("arcgisBookmarkSelect", (event) => {
    expandElement.expanded = false;
  });
</script>

arcgisClose

Event

arcgisClose: CustomEvent<void>

Emitted when the component's close button is clicked.

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "state"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisReady

Event

arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready to be interacted with.