arcgis-sketch | References | ArcGIS Maps SDK for JavaScript

ESM

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

Inheritance:: ArcgisSketch→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Sketch component provides a simple UI for creating and updating graphics on a MapView or a SceneView.

Demo

Properties

Property	Attribute	Type
`activeTool` readonly reflected	`active-tool`	`SketchTool \| SelectionTool \| null`
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`availableCreateTools`		`Array<CreateTool> \| null \| undefined`
`createGraphic` readonly		`Graphic \| null \| undefined`
`creationMode`	`creation-mode`	`CreationMode`
`defaultCreateOptions`		`CreateOptions`
`defaultGraphicsLayerDisabled`	`default-graphics-layer-disabled`	`boolean`
`defaultUpdateOptions`		`UpdateOptions`
`hideCreateToolsCircle`	`hide-create-tools-circle`	`boolean`
`hideCreateToolsMultipoint`	`hide-create-tools-multipoint`	`boolean`
`hideCreateToolsPoint`	`hide-create-tools-point`	`boolean`
`hideCreateToolsPolygon`	`hide-create-tools-polygon`	`boolean`
`hideCreateToolsPolyline`	`hide-create-tools-polyline`	`boolean`
`hideCreateToolsRectangle`	`hide-create-tools-rectangle`	`boolean`
`hideDeleteButton`	`hide-delete-button`	`boolean`
`hideDuplicateButton`	`hide-duplicate-button`	`boolean`
`hideLabelsToggle`	`hide-labels-toggle`	`boolean`
`hideSelectionCountLabel`	`hide-selection-count-label`	`boolean`
`hideSelectionToolsLassoSelection`	`hide-selection-tools-lasso-selection`	`boolean`
`hideSelectionToolsRectangleSelection`	`hide-selection-tools-rectangle-selection`	`boolean`
`hideSettingsMenu`	`hide-settings-menu`	`boolean`
`hideSnappingControls`	`hide-snapping-controls`	`boolean`
`hideSnappingControlsElementsEnabledToggle`	`hide-snapping-controls-elements-enabled-toggle`	`boolean`
`hideSnappingControlsElementsFeatureEnabledToggle`	`hide-snapping-controls-elements-feature-enabled-toggle`	`boolean`
`hideSnappingControlsElementsLayerList`	`hide-snapping-controls-elements-layer-list`	`boolean`
`hideSnappingControlsElementsSelfEnabledToggle`	`hide-snapping-controls-elements-self-enabled-toggle`	`boolean`
`hideTooltipsToggle`	`hide-tooltips-toggle`	`boolean`
`hideUndoRedoMenu`	`hide-undo-redo-menu`	`boolean`
`icon`	`icon`	`Icon["icon"]`
`label`	`label`	`string`
`labelOptions`		`SketchLabelOptions`
`layer`		`GraphicsLayer \| MapNotesLayer \| null \| undefined`
`layout`	`layout`	`Layout`
`pointSymbol`		`SketchPointSymbol`
`polygonSymbol`		`SketchPolygonSymbol`
`polylineSymbol`		`SketchPolylineSymbol`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`showCreateToolsFreehandPolygon`	`show-create-tools-freehand-polygon`	`boolean`
`showCreateToolsFreehandPolyline`	`show-create-tools-freehand-polyline`	`boolean`
`showCreateToolsText`	`show-create-tools-text`	`boolean`
`showSnappingControlsElementsHeader`	`show-snapping-controls-elements-header`	`boolean`
`snappingOptions`		`SnappingOptions`
`state` readonly		`State`
`textSymbol`		`TextSymbol`
`toolbarKind`	`toolbar-kind`	`ToolbarKind`
`tooltipOptions`		`SketchTooltipOptions`
`updateGraphics` readonly		`Collection<Graphic>`
`useLegacyCreateTools` deprecated	`use-legacy-create-tools`	`boolean`
`view`		`MapViewOrSceneView \| null \| undefined`
`visualScale`	`visual-scale`	`Button["scale"]`

activeTool

readonlyreflected Property

Type: SketchTool | SelectionTool | null

When creating new graphics (for example after create() has been called), this property reflects the create tool being used. When updating graphics (for example after update() has been called), this property reflects the update tool being used. If no create or update operation is in progress, this is null.

Prior to 4.32, creation tools were modeled as a combination of a geometry type (point, line, polygon) and an interaction mode (click, freehand, hybrid). At 4.32, the available create tools were expanded to include "freehandPolyline" and "freehandPolygon". These tools are made available to enable interoperability with other components of the ArcGIS system, where freehand polyline is a distinct create tool from polyline.

To minimize compatibility issues, if "freehandPolyline" and "freehandPolygon" are not in the list of available create tools, they will not be returned by this property, even if the user is drawing a polygon in freehand mode.

To opt in to freehandPolyline and freehandPolygon tools, include them when setting availableCreateTools, and hideCreateTools* properties

Attribute: active-tool

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

availableCreateTools

Property

Type: Array<CreateTool> | null | undefined

Property controlling the visibility and order of create tool buttons. Create tool buttons will only be rendered if they are in this collections and the matching hide/show property or attribute is configured to show the tool.

Default value: ["point", "polyline", "freehandPolyline", "polygon", "freehandPolygon", "rectangle", "circle"]

createGraphic

readonly Property

Type: Graphic | null | undefined

The graphic that is being created.

creationMode

Property

Type: CreationMode

Defines the default behavior once the create() operation is completed. By default, the user will be able to continuously create graphics with same geometry types.

Possible Values

Value	Description
continuous	This is the default. Users can continue creating graphics with same geometry types.
single	User can create a single graphic with the specified geometry type. User must choose an operation once the graphic is created.
update	The graphic will be selected for an update() operation once the `create` operation is completed.

Attribute: creation-mode
Default value: "continuous"

defaultCreateOptions

Property

Type: CreateOptions

Default create options set for the Sketch component.

defaultGraphicsLayerDisabled

Property

Type: boolean

By default, sketch will auto-create a new graphics layer if none was provided. Set this prop to true to disable this behavior.

Attribute: default-graphics-layer-disabled
Default value: false

defaultUpdateOptions

Property

Type: UpdateOptions

Default update options set for the Sketch component. Update options set on this property will be overwritten if the update options are changed when update() method is called.

Example

// Turn off highlights for update operations
const sketch = new Sketch({
 view,
 defaultUpdateOptions: {
   highlightOptions: {
     enabled: false
   }
 }
});
// Turn off highlights from the update() method
const updateOptions = { tool: "reshape", highlightOptions: { enabled: false }};
sketch.update(graphic, updateOptions);

hideCreateToolsCircle

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the circle sketch tool.

Attribute: hide-create-tools-circle
Default value: false

hideCreateToolsMultipoint

Property

Type: boolean

Indicates whether to hide the multipoint tool. Regardless of setting, multipoint is not available when working with a scene view.

The multipoint tool is excluded from availableCreateTools by default. Even if this property is false, multipoint will not be available until it is added to availableCreateTools.

Attribute: hide-create-tools-multipoint
Default value: false

hideCreateToolsPoint

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the point sketch tool.

Attribute: hide-create-tools-point
Default value: false

hideCreateToolsPolygon

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the polygon sketch tool.

Attribute: hide-create-tools-polygon
Default value: false

hideCreateToolsPolyline

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the polyline sketch tool.

Attribute: hide-create-tools-polyline
Default value: false

hideCreateToolsRectangle

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the rectangle sketch tool.

Attribute: hide-create-tools-rectangle
Default value: false

hideDeleteButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the 'delete' button while a graphic is selected. Do not hide this button without giving users on touch devices another way to delete selected geometries.

Attribute: hide-delete-button
Default value: false

hideDuplicateButton

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the 'duplicate' button while a graphic is selected.

Attribute: hide-duplicate-button
Default value: false

hideLabelsToggle

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the sketch labels toggle`.

Attribute: hide-labels-toggle
Default value: false

hideSelectionCountLabel

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide a label indicating the length of the currently selected feature set.

Attribute: hide-selection-count-label
Default value: false

hideSelectionToolsLassoSelection

Property

Type: boolean

Attribute: hide-selection-tools-lasso-selection
Default value: false

hideSelectionToolsRectangleSelection

Property

Type: boolean

Attribute: hide-selection-tools-rectangle-selection
Default value: false

hideSettingsMenu

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the settings menu. Currently this menu contains snapping options`.

Attribute: hide-settings-menu
Default value: false

hideSnappingControls

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the SnappingControls component.

Attribute: hide-snapping-controls
Default value: false

hideSnappingControlsElementsEnabledToggle

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the enabledToggle (Enable snapping). This toggles the SnappingOptions#enabled property.

Note

It is recommended to set SnappingControls.snappingOptions.enabled = true if enabledToggle is set to false. This is because selfEnabledToggle and featureEnabledToggle require snapping globally to be enabled in order to be interactive. Otherwise, these toggles will not be responsive.

Attribute: hide-snapping-controls-elements-enabled-toggle
Default value: false

hideSnappingControlsElementsFeatureEnabledToggle

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the featureEnabledToggle (Feature to feature). This toggles the SnappingOptions#featureEnabled property.

Attribute: hide-snapping-controls-elements-feature-enabled-toggle
Default value: false

hideSnappingControlsElementsLayerList

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the FeatureSnappingLayerSource layerList. The layerlist provides the available layer sources supported for snapping.

Attribute: hide-snapping-controls-elements-layer-list
Default value: false

hideSnappingControlsElementsSelfEnabledToggle

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the selfEnabledToggle (Geometry guides). This toggles the SnappingOptions#selfEnabled property.

Attribute: hide-snapping-controls-elements-self-enabled-toggle
Default value: false

hideTooltipsToggle

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the tooltips toggle`.

Attribute: hide-tooltips-toggle
Default value: false

hideUndoRedoMenu

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the undo/redo menu within the component.

Attribute: hide-undo-redo-menu
Default value: false

icon

autocast Property

Type: Icon["icon"]

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: "pencil"

label

Property

Type: string

The component's default label.

Attribute: label

labelOptions

Property

Type: SketchLabelOptions

Options to configure the sketch labels shown next to each segment of the geometry being created or updated.

Known Limitation

Sketch labels are currently only supported when working with a SceneView.

layer

Property

Type: GraphicsLayer | MapNotesLayer | null | undefined

The GraphicsLayer associated with the Sketch component. The Sketch component adds new graphics to this layer or can only update graphics stored in this layer.

layout

Property

Type: Layout

Determines the layout/orientation of the Sketch component.

Attribute: layout
Default value: "horizontal"

pointSymbol

Property

Type: SketchPointSymbol

A SimpleMarkerSymbol, PictureMarkerSymbol, PointSymbol3D, TextSymbol, CIMSymbol, or WebStyleSymbol used for representing the point geometry that is being drawn. SimpleMarkerSymbol may also be used to symbolize point features in a SceneView. However, it is recommended you use PointSymbol3D instead.

Known Limitation To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance.

The default value is the following:

{
  type: "simple-marker",
  style: "circle",
  size: 6,
  color: [255, 255, 255],
  outline: {
   color: [50, 50, 50],
    width: 1
  }
}

polygonSymbol

Property

Type: SketchPolygonSymbol

A SimpleFillSymbol, PolygonSymbol3D, or CIMSymbol used for representing the polygon geometry that is being drawn. SimpleFillSymbol may also be used to symbolize polygon features in a SceneView. However, it is recommended you use PolygonSymbol3D instead.

Known Limitation To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance.

The default value is the following:

{
  type: "simple-fill",
  color: [150, 150, 150, 0.2],
  outline: {
    color: [50, 50, 50],
    width: 2
  }
}

polylineSymbol

Property

Type: SketchPolylineSymbol

A SimpleLineSymbol, LineSymbol3D, or CIMSymbol used for representing the polyline geometry that is being drawn. SimpleLineSymbol may also be used to symbolize polyline features in a SceneView. However, it is recommended you use LineSymbol3D instead.

Known Limitation To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance.

The default value is the following:

{
  type: "simple-line",
  color: [130, 130, 130],
  width: 2
}

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

showCreateToolsFreehandPolygon

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to display the freehandPolygon tool.

Attribute: show-create-tools-freehand-polygon
Default value: false

showCreateToolsFreehandPolyline

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to display the freehandPolyline tool.

Attribute: show-create-tools-freehand-polyline
Default value: false

showCreateToolsText

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to display the text tool.

Attribute: show-create-tools-text
Default value: false

showSnappingControlsElementsHeader

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to display the header.

Attribute: show-snapping-controls-elements-header
Default value: false

snappingOptions

Property

Type: SnappingOptions

The SnappingOptions for sketching. It supports self and feature snapping.

state

readonly Property

Type: State

The current state of the component.

textSymbol

Property

Type: TextSymbol

Since: ArcGIS Maps SDK for JavaScript 5.0

A TextSymbol used for representing the geometry that is being drawn.

Known Limitation To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance.

The default value is the following:

{
  type: "text",
  text: "hello world"
}

toolbarKind

Property

Type: ToolbarKind

Since: ArcGIS Maps SDK for JavaScript 4.32

Controls the appearance of the sketch component, allowing the toolbar to adapt its appearance appropriately based on context.

Set this to docked for use within the Expand component, or any other situation where Sketch is not floating within a large canvas.

Attribute: toolbar-kind
Default value: "floating"

tooltipOptions

Property

Type: SketchTooltipOptions

Options to configure the tooltip shown next to the cursor when creating or updating graphics.

updateGraphics

readonly Property

Type: Collection<Graphic>

An array of graphics that are being updated by the Sketch component.

useLegacyCreateTools

deprecated Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

Starting at version 5.0, arcgis-sketch is transitioning to a next generation geometry creation experience. This new experience provides advanced curve creation tools and allows multiple tools to be used in combination to define a single geometry.

As of 5.0, this experience is only available in 2D (e.g. arcgis-map).

This property is available to allow 2D applications to temporarily opt out of this experience.

This option will be removed in an upcoming release.

Attribute: use-legacy-create-tools
Default value: false

view

Property

Type: MapViewOrSceneView | null | 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-sketch component will be associated with a map or scene component rather than using the view property.

visualScale

Property

Type: Button["scale"]

Since: ArcGIS Maps SDK for JavaScript 5.0

Specifies the size of the component.

Attribute: visual-scale

Methods

Method	Signature
`cancel`	`cancel(): Promise<void>`
`complete`	`complete(): Promise<void>`
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`create`	`create(tool: CreateTool, createOptions?: CreateOptions): Promise<void>`
`delete`	`delete(): Promise<void>`
`destroy`	`destroy(): Promise<void>`
`duplicate`	`duplicate(): Promise<void>`
`redo`	`redo(): Promise<void>`
`triggerUpdate`	`triggerUpdate(graphic: Parameters<Sketch["update"]>[0], updateOptions?: Parameters<Sketch["update"]>[1]): Promise<void>`
`undo`	`undo(): Promise<void>`

cancel

Method

Signature: cancel (): Promise<void>

Returns: Promise<void>

complete

Method

Signature: complete (): Promise<void>

Returns: 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 arcgisSketch = document.querySelector("arcgis-sketch");
document.body.append(arcgisSketch);
await arcgisSketch.componentOnReady();
console.log("arcgis-sketch is ready to go!");

create

Method

Signature: create (tool: CreateTool, createOptions?: CreateOptions): Promise<void>

Parameters

Parameter	Type	Description	Required
tool	`CreateTool`
createOptions	`CreateOptions`

Returns: Promise<void>

delete

Method

Signature: delete (): Promise<void>

Returns: Promise<void>

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

duplicate

Method

Signature: duplicate (): Promise<void>

Returns: Promise<void>

redo

Method

Signature: redo (): Promise<void>

Returns: Promise<void>

triggerUpdate

Method

Signature: triggerUpdate (graphic: Parameters<Sketch["update"]>[0], updateOptions?: Parameters<Sketch["update"]>[1]): Promise<void>

Parameters

Parameter	Type	Description	Required
graphic	`Parameters<Sketch["update"]>[0]`
updateOptions	`Parameters<Sketch["update"]>[1]`

Returns: Promise<void>

undo

Method

Signature: undo (): Promise<void>

Returns: Promise<void>

Events

Name	Type
`arcgisCreate`	CustomEvent<CreateEvent>
`arcgisDelete`	CustomEvent<DeleteEvent>
`arcgisPropertyChange`	CustomEvent<{ name: "state"; }>
`arcgisReady`	CustomEvent<void>
`arcgisRedo`	CustomEvent<RedoEvent>
`arcgisUndo`	CustomEvent<UndoEvent>
`arcgisUpdate`	CustomEvent<UpdateEvent>

arcgisCreate

Event

arcgisCreate: CustomEvent<CreateEvent>

arcgisDelete

Event

arcgisDelete: CustomEvent<DeleteEvent>

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.

arcgisRedo

Event

arcgisRedo: CustomEvent<RedoEvent>

arcgisUndo

Event

arcgisUndo: CustomEvent<UndoEvent>

arcgisUpdate

Event

arcgisUpdate: CustomEvent<UpdateEvent>