Sketch

ESM:

Use dark colors for code blocksCopy
import "@arcgis/map-components/components/arcgis-sketch";

CDN:

No specific import is needed for this component.

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` readonlyreflected	`active-tool`	`"circle" \| "custom-selection" \| "freehandPolygon" \| "freehandPolyline" \| "lasso-selection" \| "mesh" \| "move" \| "multipoint" \| "point" \| "polygon" \| "polyline" \| "rectangle" \| "rectangle-selection" \| "reshape" \| "text" \| "transform"`
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`availableCreateTools`		`Array<"circle" \| "point" \| "polygon" \| "rectangle" \| "text" \| "multipoint" \| "polyline" \| "mesh" \| "freehandPolyline" \| "freehandPolygon">`
`createGraphic` readonly		`Graphic`
`creationMode`	`creation-mode`	`"continuous" \| "single" \| "update"`
`defaultCreateOptions`		`SketchDefaultCreateOptions`
`defaultGraphicsLayerDisabled`	`default-graphics-layer-disabled`	`boolean`
`defaultUpdateOptions`		`SketchDefaultUpdateOptions`
`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`	`string`
`label`	`label`	`string`
`labelOptions`		`SketchLabelOptions`
`layer`		`GraphicsLayer \| MapNotesLayer`
`layout`	`layout`	`"horizontal" \| "vertical"`
`pointSymbol`		`CIMSymbol \| PictureMarkerSymbol \| PointSymbol3D \| SimpleMarkerSymbol \| TextSymbol \| WebStyleSymbol`
`polygonSymbol`		`CIMSymbol \| PolygonSymbol3D \| SimpleFillSymbol`
`polylineSymbol`		`CIMSymbol \| LineSymbol3D \| SimpleLineSymbol`
`position` deprecated	`position`	`"bottom-leading" \| "bottom-left" \| "bottom-right" \| "bottom-trailing" \| "manual" \| "top-leading" \| "top-left" \| "top-right" \| "top-trailing"`
`referenceElement`	`reference-element`	`HTMLArcgisLinkChartElement \| HTMLArcgisMapElement \| HTMLArcgisSceneElement \| string`
`scale`	`scale`	`"l" \| "m" \| "s"`
`showCreateToolsFreehandPolygon`	`show-create-tools-freehand-polygon`	`boolean`
`showCreateToolsFreehandPolyline`	`show-create-tools-freehand-polyline`	`boolean`
`showSnappingControlsElementsHeader`	`show-snapping-controls-elements-header`	`boolean`
`snappingOptions`		`SnappingOptions`
`state` readonlyreflected	`state`	`"active" \| "disabled" \| "ready"`
`toolbarKind`	`toolbar-kind`	`"docked" \| "floating"`
`tooltipOptions`		`SketchTooltipOptions`
`updateGraphics` readonly		`Collection<Graphic>`
`view`		`MapView \| SceneView`

activeTool

readonly

Property

activeTool: "circle" | "custom-selection" | "freehandPolygon" | "freehandPolyline" | "lasso-selection" | "mesh" | "move" | "multipoint" | "point" | "polygon" | "polyline" | "rectangle" | "rectangle-selection" | "reshape" | "text" | "transform"

When creating new graphics (for example after create() has been called), this property reflects the create tool being used.

Attribute: active-tool

autoDestroyDisabled

Property

autoDestroyDisabled: 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

availableCreateTools: Array<"circle" | "point" | "polygon" | "rectangle" | "text" | "multipoint" | "polyline" | "mesh" | "freehandPolyline" | "freehandPolygon">

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

readonlyProperty

createGraphic: Graphic

The graphic that is being created.

creationMode

Property

creationMode: "continuous" | "single" | "update"

Defines the default behavior once the create operation is completed.

Attribute: creation-mode
Default value: "continuous"

defaultCreateOptions

Property

defaultCreateOptions: SketchDefaultCreateOptions

Default create options set for the Sketch widget.

defaultGraphicsLayerDisabled

Property

defaultGraphicsLayerDisabled: 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

defaultUpdateOptions: SketchDefaultUpdateOptions

Default update options set for the Sketch widget.

hideCreateToolsCircle

Property

hideCreateToolsCircle: boolean

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

hideCreateToolsMultipoint

Property

hideCreateToolsMultipoint: boolean

Indicates whether to display 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: true

hideCreateToolsPoint

Property

hideCreateToolsPoint: boolean

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

hideCreateToolsPolygon

Property

hideCreateToolsPolygon: boolean

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

hideCreateToolsPolyline

Property

hideCreateToolsPolyline: boolean

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

hideCreateToolsRectangle

Property

hideCreateToolsRectangle: boolean

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

hideDeleteButton

Property

hideDeleteButton: boolean

Attribute: hide-delete-button
Default value: false

hideDuplicateButton

Property

hideDuplicateButton: boolean

Attribute: hide-duplicate-button
Default value: false

hideLabelsToggle

Property

hideLabelsToggle: boolean

Attribute: hide-labels-toggle
Default value: false

hideSelectionCountLabel

Property

hideSelectionCountLabel: boolean

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

hideSelectionToolsLassoSelection

Property

hideSelectionToolsLassoSelection: boolean

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

hideSelectionToolsRectangleSelection

Property

hideSelectionToolsRectangleSelection: boolean

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

hideSettingsMenu

Property

hideSettingsMenu: boolean

Attribute: hide-settings-menu
Default value: false

hideSnappingControls

Property

hideSnappingControls: boolean

Attribute: hide-snapping-controls
Default value: false

hideSnappingControlsElementsEnabledToggle

Property

hideSnappingControlsElementsEnabledToggle: boolean

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

hideSnappingControlsElementsFeatureEnabledToggle

Property

hideSnappingControlsElementsFeatureEnabledToggle: boolean

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

hideSnappingControlsElementsLayerList

Property

hideSnappingControlsElementsLayerList: boolean

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

hideSnappingControlsElementsSelfEnabledToggle

Property

hideSnappingControlsElementsSelfEnabledToggle: boolean

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

hideTooltipsToggle

Property

hideTooltipsToggle: boolean

Attribute: hide-tooltips-toggle
Default value: false

hideUndoRedoMenu

Property

hideUndoRedoMenu: boolean

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

icon

Property

icon: string

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

label: string

The Sketch widget's default label.

Attribute: label

labelOptions

Property

labelOptions: SketchLabelOptions

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

layer

Property

layer: GraphicsLayer | MapNotesLayer

The GraphicsLayer associated with the Sketch widget.

layout

Property

layout: "horizontal" | "vertical"

Determines the layout/orientation of the Sketch widget.

Attribute: layout
Default value: "horizontal"

pointSymbol

Property

A SimpleMarkerSymbol, PointSymbol3D, TextSymbol, CIMSymbol, or WebStyleSymbol used for representing the point geometry that is being drawn.

polygonSymbol

Property

polygonSymbol: CIMSymbol | PolygonSymbol3D | SimpleFillSymbol

A SimpleFillSymbol, PolygonSymbol3D, or CIMSymbol used for representing the polygon geometry that is being drawn.

polylineSymbol

Property

polylineSymbol: CIMSymbol | LineSymbol3D | SimpleLineSymbol

A SimpleLineSymbol, LineSymbol3D, or CIMSymbol used for representing the polyline geometry that is being drawn.

position

deprecatedProperty

position: "bottom-leading" | "bottom-left" | "bottom-right" | "bottom-trailing" | "manual" | "top-leading" | "top-left" | "top-right" | "top-trailing"

Deprecatedsince 4.34, use slot instead.

Attribute: position

referenceElement

Property

referenceElement: HTMLArcgisLinkChartElement | HTMLArcgisMapElement | HTMLArcgisSceneElement | string

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

scale

Property

scale: "l" | "m" | "s"

Determines the size of widget elements.

Attribute: scale
Default value: "m"

showCreateToolsFreehandPolygon

Property

showCreateToolsFreehandPolygon: boolean

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

showCreateToolsFreehandPolyline

Property

showCreateToolsFreehandPolyline: boolean

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

showSnappingControlsElementsHeader

Property

showSnappingControlsElementsHeader: boolean

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

snappingOptions

Property

snappingOptions: SnappingOptions

The SnappingOptions for sketching.

state

readonly

Property

state: "active" | "disabled" | "ready"

The current state of the component.

Attribute: state

toolbarKind

Property

toolbarKind: "docked" | "floating"

Controls the appearance of the sketch widget, 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

tooltipOptions: SketchTooltipOptions

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

updateGraphics

readonlyProperty

updateGraphics: Collection<Graphic>

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

view

Property

view: MapView | SceneView

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

Methods

Method	Signature
`cancel`	`cancel(): Promise<void>`
`complete`	`complete(): Promise<void>`
`componentOnReady`	`componentOnReady(): Promise<void>`
`create`	`create(tool: "circle" \| "freehandPolygon" \| "freehandPolyline" \| "multipoint" \| "point" \| "polygon" \| "polyline" \| "rectangle", createOptions?: __esri.SketchViewModelCreateCreateOptions): Promise<void>`
`delete`	`delete(): Promise<void>`
`destroy`	`destroy(): Promise<void>`
`duplicate`	`duplicate(): Promise<void>`
`redo`	`redo(): Promise<void>`
`triggerUpdate`	`triggerUpdate(graphic: __esri.Graphic \| __esri.Graphic[], updateOptions?: __esri.SketchViewModelUpdateUpdateOptions): Promise<void>`
`undo`	`undo(): Promise<void>`

cancel

Method

cancel(): Promise<void>

Returns: Promise<void>

complete

Method

complete(): Promise<void>

Returns: Promise<void>

componentOnReady

Method

componentOnReady(): Promise<void>

Create a promise that resolves once component is fully loaded.

Example

Use dark colors for code blocksCopy
const arcgisSketch = document.querySelector("arcgis-sketch");
document.body.append(arcgisSketch);
await arcgisSketch.componentOnReady();
console.log("arcgis-sketch is ready to go!");

Returns: Promise<void>

create

Method

create(tool: "circle" | "freehandPolygon" | "freehandPolyline" | "multipoint" | "point" | "polygon" | "polyline" | "rectangle", createOptions?: __esri.SketchViewModelCreateCreateOptions): Promise<void>

Parameters

Parameter	Type	Optional?
tool	`"circle" \| "freehandPolygon" \| "freehandPolyline" \| "multipoint" \| "point" \| "polygon" \| "polyline" \| "rectangle"`
createOptions	`SketchViewModelCreateCreateOptions \| undefined`

Returns: Promise<void>

delete

Method

delete(): Promise<void>

Returns: Promise<void>

destroy

Method

destroy(): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

duplicate

Method

duplicate(): Promise<void>

Returns: Promise<void>

redo

Method

redo(): Promise<void>

Returns: Promise<void>

triggerUpdate

Method

triggerUpdate(graphic: __esri.Graphic | __esri.Graphic[], updateOptions?: __esri.SketchViewModelUpdateUpdateOptions): Promise<void>

Parameters

Parameter	Type	Optional?
graphic	`Array<[Graphic](https://next.gha.afd.arcgis.com/javascript/latest/api-reference/esri-Graphic.html)> \| Graphic`
updateOptions	`SketchViewModelUpdateUpdateOptions \| undefined`

Returns: Promise<void>

undo

Method

undo(): Promise<void>

Returns: Promise<void>

Events

Event	Type
`arcgisCreate`	`CustomEvent<SketchCreateEvent>`
`arcgisDelete`	`CustomEvent<SketchDeleteEvent>`
`arcgisPropertyChange`	`CustomEvent<{ name: "state"; }>`
`arcgisReady`	`CustomEvent<void>`
`arcgisRedo`	`CustomEvent<SketchRedoEvent>`
`arcgisUndo`	`CustomEvent<SketchUndoEvent>`
`arcgisUpdate`	`CustomEvent<SketchUpdateEvent>`

arcgisCreate

Event

arcgisCreate: CustomEvent<SketchCreateEvent>

arcgisDelete

Event

arcgisDelete: CustomEvent<SketchDeleteEvent>

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<SketchRedoEvent>

arcgisUndo

Event

arcgisUndo: CustomEvent<SketchUndoEvent>

arcgisUpdate

Event

arcgisUpdate: CustomEvent<SketchUpdateEvent>