ESM
import "@arcgis/map-components/components/arcgis-sketch";
Inheritance
ArcgisSketch→HTMLElement
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

PropertyAttributeType
active-create-tool-draw-mode
"click" | "freehand" | "hybrid" | null | undefined
readonly
auto-destroy-disabled
readonly
creation-mode
default-graphics-layer-disabled
hide-create-tools-circle
hide-create-tools-multipoint
hide-create-tools-point
hide-create-tools-polygon
hide-create-tools-polyline
hide-create-tools-rectangle
hide-delete-button
hide-duplicate-button
hide-geometry-simplification-activity-indicator
hide-labels-toggle
hide-selection-count-label
hide-selection-tools-lasso-selection
hide-selection-tools-rectangle-selection
hide-settings-menu
hide-snapping-controls
hide-snapping-controls-elements-enabled-toggle
hide-snapping-controls-elements-feature-enabled-toggle
hide-snapping-controls-elements-grid-controls
hide-snapping-controls-elements-grid-controls-elements-color-selection
hide-snapping-controls-elements-grid-controls-elements-dynamic-scale-toggle
hide-snapping-controls-elements-grid-controls-elements-line-interval-input
hide-snapping-controls-elements-grid-controls-elements-numeric-inputs
hide-snapping-controls-elements-grid-controls-elements-out-of-scale-warning
hide-snapping-controls-elements-grid-controls-elements-placement-buttons
hide-snapping-controls-elements-grid-controls-elements-rotate-with-map-toggle
hide-snapping-controls-elements-grid-enabled-toggle
hide-snapping-controls-elements-layer-list
hide-snapping-controls-elements-self-enabled-toggle
hide-tooltips-toggle
hide-undo-redo-menu
icon
label
reflected
layout
"horizontal" | "vertical"
reference-element
relative-position
deprecated
scale
Button["scale"]
show-create-tools-freehand-polygon
show-create-tools-freehand-polyline
show-create-tools-text
show-snapping-controls-elements-header
readonly
SketchViewModel["state"]
reflected
toolbar-kind
"docked" | "floating"
readonly
update-on-graphic-click-disabled
use-legacy-create-tools
use-view-options
visual-scale
Button["scale"]

activeCreateToolDrawMode

Property
Type
"click" | "freehand" | "hybrid" | null | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

The drawing mode (freehand, hybrid, or click) used by the active create tool. The drawing mode affects how clicks, touches, and drag gestures are interpreted during drawing. If no create operation is in progress, this is null.

Attribute
active-create-tool-draw-mode

activeFillSymbol

Property
Type
CIMSymbol | SimpleFillSymbol | null | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

The SimpleFillSymbol displayed when actively creating a new polygon graphic.

Known Limitation Not supported in 3D SceneViews. To avoid unintended side effects, instantiate a new symbol rather than modifying the current instance.

The default value is the following:

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

activeLineSymbol

Property
Type
CIMSymbol | SimpleLineSymbol | null | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

The CIMSymbol displayed when actively creating a new polyline graphic. This differs from polylineSymbol, which is displayed when the graphic has been completed. Setting this symbol also affects the default outline symbol when actively creating a new polygon. A SimpleLineSymbol is also a valid symbol to use.

The default value is the following:

new CIMSymbol({
data: {
type: "CIMSymbolReference",
symbol: {
type: "CIMLineSymbol",
symbolLayers: [
{
type: "CIMSolidStroke",
effects: [
{
type: "CIMGeometricEffectDashes",
dashTemplate: [3.75, 3.75],
lineDashEnding: "HalfPattern",
controlPointEnding: "NoConstraint"
}
],
enable: true,
capStyle: "Butt",
joinStyle: "Round",
miterLimit: 10,
width: 1.6,
color: [255, 255, 255, 255]
},
{
type: "CIMSolidStroke",
enable: true,
capStyle: "Butt",
joinStyle: "Round",
miterLimit: 10,
width: 2,
color: [0, 0, 0, 255]
}
]
}
}
});

activeTool

readonly Property
Type
SelectionTool | SketchTool | undefined

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 triggerUpdate() has been called), this property reflects the update tool being used. It also reflects the active selection tool. If no tool is active, this is undefined.

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.

activeTooltip

Property
Type
Tooltip | null
Since
ArcGIS Maps SDK for JavaScript 5.2

The tooltip currently being displayed for activeTool. Returns null when no tooltip is visible.

activeVertexSymbol

Property
Type
SimpleMarkerSymbol | CIMSymbol | null | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

The symbol used to indicate active vertices while creating graphics.

This symbol is only used with the legacy create tools.

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
Example
<arcgis-sketch auto-destroy-disabled></arcgis-sketch>
sketchElement.autoDestroyDisabled = true;

availableCreateTools

Property
Type
CreateTool[] | undefined

Property controlling the visibility and order of create tool buttons. Create tool buttons will only be rendered if they are in this collection 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

ValueDescription
continuousThis is the default. Users can continue creating graphics with same geometry types.
singleUser can create a single graphic with the specified geometry type. User must choose an operation once the graphic is created.
updateThe 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. Options passed to create() override these defaults for that operation.

defaultGraphicsLayerDisabled

Property
Type
boolean

By default, sketch will create and manage a graphics layer.

Set this property to true to disable this behavior. Disabling the default graphics layer is recommended if supplying your own layer.

Attribute
default-graphics-layer-disabled
Default value
false

defaultUpdateOptions

Property
Type
UpdateOptions

Default update options set for the Sketch component. Options passed to triggerUpdate() override these defaults for that operation.

Example
// Turn off highlights for update operations
const sketch = document.querySelector("arcgis-sketch");
sketch.defaultUpdateOptions = {
highlightOptions: {
enabled: false
}
};
// Override options for an individual update operation
const updateOptions = { tool: "reshape", highlightOptions: { enabled: false }};
await sketch.triggerUpdate(graphic, updateOptions);

geometrySimplificationInProgress

readonly Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates whether an asynchronous geometry simplification operation is in progress.

New create and update operations are blocked while this is true. Call cancel() to cancel the long-running operation.

Default value
false

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

hideGeometrySimplificationActivityIndicator

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates whether to hide display of the geometry simplification progress indicator while geometry simplification is in progress.

When set to true, the progress indicator is not shown.

Attribute
hide-geometry-simplification-activity-indicator
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
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates whether to hide the 'lasso' (freehand polygon) selection tool.

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

hideSelectionToolsRectangleSelection

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates whether to hide the rectangle selection tool.

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. The settings menu includes controls for tooltips, segment labels, grid display, and snapping.

Attribute
hide-settings-menu
Default value
false

hideSnappingControls

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to hide the snapping controls portion of the settings menu. This property is preserved but ignored while useViewOptions is true.

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.

This property is preserved but ignored while useViewOptions is true.

Note

It is recommended to set snappingOptions.enabled to true if hideSnappingControlsElementsEnabledToggle is set to true. 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. This property is preserved but ignored while useViewOptions is true.

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

hideSnappingControlsElementsGridControls

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the gridControls (configuration of the snapping grid). This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-controls
Default value
false

hideSnappingControlsElementsGridControlsElementsColorSelection

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the colorSelection within the snapping grid controls. This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-controls-elements-color-selection
Default value
false

hideSnappingControlsElementsGridControlsElementsDynamicScaleToggle

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the dynamicScaleToggle within the snapping grid controls. This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-controls-elements-dynamic-scale-toggle
Default value
false

hideSnappingControlsElementsGridControlsElementsLineIntervalInput

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the lineIntervalInput within the snapping grid controls. This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-controls-elements-line-interval-input
Default value
false

hideSnappingControlsElementsGridControlsElementsNumericInputs

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the numericInputs within the snapping grid controls. This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-controls-elements-numeric-inputs
Default value
false

hideSnappingControlsElementsGridControlsElementsOutOfScaleWarning

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the outOfScaleWarning within the snapping grid controls. This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-controls-elements-out-of-scale-warning
Default value
false

hideSnappingControlsElementsGridControlsElementsPlacementButtons

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the placementButtons within the snapping grid controls. This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-controls-elements-placement-buttons
Default value
false

hideSnappingControlsElementsGridControlsElementsRotateWithMapToggle

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the rotateWithMapToggle within the snapping grid controls. This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-controls-elements-rotate-with-map-toggle
Default value
false

hideSnappingControlsElementsGridEnabledToggle

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to hide the gridEnabledToggle (snap-to-grid). This property is preserved but ignored while useViewOptions is true.

Attribute
hide-snapping-controls-elements-grid-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. This property is preserved but ignored while useViewOptions is true.

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. This property is preserved but ignored while useViewOptions is true.

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. This property is preserved but ignored while useViewOptions is true.

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

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
Attribute
icon
Default value
"pencil"

label

Property
Type
string | undefined

The component's default label.

Attribute
label
Default value
"Sketch"

labelOptions

Property
Type
SketchLabelOptions

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

layer

Property
Type
GraphicsLayer | MapNotesLayer | SketchLayer | null | undefined

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

layout

reflected Property
Type
"horizontal" | "vertical"

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
Attribute
reference-element

relativePosition

autocast Property
Type
RelativePosition
Since
ArcGIS Maps SDK for JavaScript 5.2

Relative position is used to control the appearance of elements rendered by arcgis-sketch. If used directly within the slots of an arcgis-map or arcgis-scene component, you do not need to manually set this value. If using custom layouts, or dynamically moving layouts between slots, prefer explicitly setting this property.

Examples of elements that depend on relative position include the split button chevrons (in vertical layout), the settings popover, and tooltips.

Attribute
relative-position
Default value
"top-right"

scale

deprecated Property
Type
Button["scale"]
Since
ArcGIS Maps SDK for JavaScript 4.32

Determines the size of component elements.

Attribute
scale
Default value
"m"

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.

Note: To display the text tool in Sketch, set showCreateToolsText to true and add "text" to the availableCreateTools array.

Attribute
show-create-tools-text
Default value
false
Example
<arcgis-map basemap="topo-vector" center="139.5716,35.696" zoom="18">
<arcgis-sketch slot="top-right" show-create-tools-text="true"></arcgis-sketch>
</arcgis-map>
<script type="module">
const sketch = document.querySelector("arcgis-sketch");
await sketch.componentOnReady();
sketch.availableCreateTools = ["text", "polyline", "polygon", "point"];
</script>

showSnappingControlsElementsHeader

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.0

Indicates whether to display the header. This property is preserved but ignored while useViewOptions is true.

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

snappingOptions

Property
Type
SnappingOptions

The SnappingOptions for sketching. It supports self and feature snapping. These options are preserved but ignored while useViewOptions is true.

state

readonly Property
Type
SketchViewModel["state"]

The Sketch component's state.

ValueDescription
disabledThe component is not ready to create or update graphics.
readyThe component is ready to start an operation.
activeA create or update operation is in progress.

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

reflected Property
Type
"docked" | "floating"
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, a panel, or any other situation where Sketch is not floating within a larger canvas (like a map or scene).

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. These options are preserved but ignored while useViewOptions is true.

updateGraphics

readonly Property
Type
Collection<Graphic>

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

updateOnGraphicClickDisabled

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.1

Indicates whether to prevent the user from clicking a graphic in the layer to start updating it. Set this property to true to implement custom MapView.hitTest logic, then call triggerUpdate() to update the chosen graphics.

Attribute
update-on-graphic-click-disabled
Default value
false

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

useViewOptions

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2
beta

If true, the component uses snapping, tooltips, display units, and input units from ViewOptions.

When this property is true:

  • Snapping and tooltip options are inherited from the view. The component's snappingOptions and tooltipOptions are preserved but ignored.
  • Snapping controls and the tooltip toggle are hidden from the component's Settings menu. Their visibility properties (e.g. hideSnappingControlsElementsGridControls) are preserved but ignored.
  • Units set through valueOptions override the corresponding units on the view, such as length or area, without changing the view's options. Setting a unit to null or undefined restores inheritance for that measurement type.

When false, the component uses its own snapping, tooltip, and unit options instead.

Label options and direction mode are not inherited from the view.

Changes to this property apply when the next create or update operation starts, not to an operation already in progress.

Attribute
use-view-options
Default value
false

valueOptions

Property
Type
SketchValueOptions

Options to configure how values are displayed and input when creating or updating graphics. See useViewOptions for unit inheritance and override behavior.

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
Default value
"m"

Methods

MethodSignature
addGraphic(graphic: Graphic): Promise<void>
addGraphics(graphics: Graphic[]): Promise<void>
cancel(): Promise<void>
canRedo(): Promise<boolean>
canUndo(): Promise<boolean>
complete(): Promise<void>
inherited
componentOnReady(): Promise<this>
create(tool: CreateTool, createOptions?: CreateOptions): Promise<void>
delete(): Promise<void>
destroy(): Promise<void>
duplicate(): Promise<void>
hasGraphic(graphic: Graphic): Promise<boolean>
place(geometry: Mesh): Promise<void>
redo(): Promise<void>
removeAllGraphics(): Promise<void>
removeGraphic(graphic: Graphic): Promise<void>
removeGraphics(graphics: Graphic[]): Promise<void>
triggerUpdate(graphic: Parameters<SketchViewModel["update"]>[0], updateOptions?: Parameters<SketchViewModel["update"]>[1]): Promise<void>
undo(): Promise<void>

addGraphic

Method
Signature
addGraphic (graphic: Graphic): Promise<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Convenience method for adding a graphic to the appropriate Sketch layer. Does not affect any active operations.

Parameters

ParameterTypeDescriptionRequired
graphic

The graphic to add.

Returns
Promise<void>

addGraphics

Method
Signature
addGraphics (graphics: Graphic[]): Promise<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Convenience method for adding multiple graphics to the appropriate Sketch layer. Does not affect any active operations.

Parameters

ParameterTypeDescriptionRequired
graphics

The graphics to add.

Returns
Promise<void>

cancel

Method
Signature
cancel (): Promise<void>

Cancels the active operation and fires the @arcgisCreate or @arcgisUpdate event. If called in the middle of a create operation, discards the partially created graphic. Also cancels pending operations and active selection tools, restoring a ready state.

Returns
Promise<void>

canRedo

Method
Signature
canRedo (): Promise<boolean>
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates if it is possible to perform a redo action.

Returns
Promise<boolean>

Resolves to true if redo is possible.

canUndo

Method
Signature
canUndo (): Promise<boolean>
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates if it is possible to perform an undo action.

Returns
Promise<boolean>

Resolves to true if undo is possible.

complete

Method
Signature
complete (): Promise<void>

Completes the active operation and fires the @arcgisCreate or @arcgisUpdate event with its state set to complete. If called in the middle of a create operation, finishes the operation and keeps the valid geometry.

Returns
Promise<void>

componentOnReady

inherited Method
Signature
componentOnReady (): Promise<this>

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

Returns
Promise<this>
Example
const arcgisSketch = document.createElement("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>

Creates a graphic with the geometry specified by tool. When the first vertex of the graphic is added, the @arcgisCreate event starts firing. The provided tool becomes the activeTool.

Parameters

ParameterTypeDescriptionRequired
tool

Name of the create tool. Specifies the geometry for the graphic to be created.

createOptions

Options for the graphic to be created. Overrides defaultCreateOptions.

Returns
Promise<void>

Resolves when the requested create tool has been loaded and is ready to use, not when the user finishes drawing.

Example
const sketch = document.querySelector("arcgis-sketch");
sketch.addEventListener("arcgisCreate", (event) => {
if (event.detail.state === "complete") {
console.log("Created graphic", event.detail.graphic);
}
});
await sketch.create("polygon", { mode: "freehand" });
// Create a square.
await sketch.create("rectangle", { preserveAspectRatio: true });
// Create an ellipse.
await sketch.create("circle", { preserveAspectRatio: false });

delete

Method
Signature
delete (): Promise<void>

Deletes the selected graphics used in the update workflow. Calling this method fires the @arcgisDelete event.

Returns
Promise<void>
Example
sketch.addEventListener("arcgisDelete", (event) => {
event.detail.graphics.forEach((graphic) => {
console.log("Deleted graphic", graphic);
});
});
await sketch.delete();

destroy

Method
Signature
destroy (): Promise<void>

Permanently destroy the component.

Returns
Promise<void>

duplicate

Method
Signature
duplicate (): Promise<void>

Duplicates the selected graphics used in the update workflow and automatically adds them to the associated layer. Calling this method fires the @arcgisDuplicate event with the duplicated graphics.

Returns
Promise<void>

hasGraphic

Method
Signature
hasGraphic (graphic: Graphic): Promise<boolean>
Since
ArcGIS Maps SDK for JavaScript 5.2

Convenience method for determining if a graphic belongs to a current Sketch layer or sublayer.

Parameters

ParameterTypeDescriptionRequired
graphic

The graphic to check.

Returns
Promise<boolean>

Resolves to true if the graphic belongs to a current Sketch layer or sublayer.

place

Method
Signature
place (geometry: Mesh): Promise<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Creates a graphic similarly to create(), but accepts the geometry directly. Placement is then completed interactively by the user. Currently only Mesh placement is supported.

The @arcgisCreate event starts firing, and a create tool becomes the activeTool until placement finishes.

Parameters

ParameterTypeDescriptionRequired
geometry

Mesh geometry to place when creating the graphic.

Returns
Promise<void>
Example
// create mesh at the global origin
const box = meshUtils.createBox(new Point({
x: 0,
y: 0,
z: 0,
spatialReference: SpatialReference.WGS84
}));
// Call place method to place a mesh - this will allow the user to place the mesh using the mouse
await sketch.place(box);
// listen to create event, only respond when event's state changes to complete
sketch.addEventListener("arcgisCreate", function(event) {
if (event.detail.state === "complete") {
// retrieve the final position of the mesh which was chosen by the user
const mesh = event.detail.graphic.geometry;
const placedLocation = mesh.origin;
}
});

redo

Method
Signature
redo (): Promise<void>

Redoes the last undone operation.

The undo/redo stack is for an individual sketch operation, meaning you can redo/undo actions while creating or updating a graphic.

Returns
Promise<void>

removeAllGraphics

Method
Signature
removeAllGraphics (): Promise<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Convenience method for removing all graphics from the appropriate Sketch layer. Any active operation will automatically be cancelled if any removed graphics are the target of an active operation.

Returns
Promise<void>

removeGraphic

Method
Signature
removeGraphic (graphic: Graphic): Promise<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Convenience method for removing a graphic from the appropriate Sketch layer. Any active operation will automatically be cancelled if the graphic is one of the targets of the active operation.

Parameters

ParameterTypeDescriptionRequired
graphic

The graphic to remove.

Returns
Promise<void>

removeGraphics

Method
Signature
removeGraphics (graphics: Graphic[]): Promise<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Convenience method for removing multiple graphics from the appropriate Sketch layer. Any active operation will automatically be cancelled if any of the graphics are the target of an active operation.

Parameters

ParameterTypeDescriptionRequired
graphics

The graphics to remove.

Returns
Promise<void>

triggerUpdate

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

Initializes an update operation for the specified graphic(s).

Parameters

ParameterTypeDescriptionRequired
graphic
Parameters<SketchViewModel["update"]>[0]

A graphic or an array of graphics to be updated. Only graphics in the sketch layer can be updated.

updateOptions
Parameters<SketchViewModel["update"]>[1]

Update options for the graphics to be updated.

Returns
Promise<void>

Resolves when the requested update tool has been loaded and is ready to use.

Example
// start update operation for the selected graphic
// with transform tool. Only allow uniform scaling operation.
await sketch.triggerUpdate([selectedGraphic], {
tool: "transform",
enableRotation: false,
enableScaling: true,
preserveAspectRatio: true,
toggleToolOnClick: false
});

undo

Method
Signature
undo (): Promise<void>

Undoes the last operation. The undo/redo stack is for an individual sketch operation, meaning you can redo/undo actions while creating or updating a graphic. The undo stack is cleared when an operation completes.

Returns
Promise<void>

Events

arcgisCreate

Event
arcgisCreate: CustomEvent<CreateEvent>

Fires when a user starts sketching a graphic, is actively sketching a graphic and completes sketching a graphic.

bubbles composed cancelable

arcgisDelete

Event
arcgisDelete: CustomEvent<DeleteEvent>

Fires when a user deletes selected graphics by clicking the Delete feature button on the Sketch widget or when the delete() method is called.

bubbles composed cancelable

arcgisDuplicate

Event
arcgisDuplicate: CustomEvent<DuplicateEvent>

Fires when the user duplicates selected graphics.

bubbles composed cancelable

arcgisPropertyChange

Event
arcgisPropertyChange: CustomEvent<{ name: "activeTool" | "geometrySimplificationInProgress" | "state"; }>

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

bubbles composed cancelable

arcgisReady

Event
arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready for user interaction.

bubbles composed cancelable

arcgisRedo

Event
arcgisRedo: CustomEvent<RedoEvent>

Fires in response to redo action during creation of a new graphic or updating existing graphics. The undo/redo stack is for an individual sketch operation, meaning you can undo/redo actions while creating or updating a graphic.

bubbles composed cancelable

arcgisUndo

Event
arcgisUndo: CustomEvent<UndoEvent>

Fires in response to undo action during creation of a new graphic or updating existing graphics. The undo/redo stack is for an individual sketch operation, meaning you can undo/redo actions while creating or updating a graphic.

bubbles composed cancelable

arcgisUpdate

Event
arcgisUpdate: CustomEvent<UpdateEvent>

Fires when the user starts updating graphics, is actively updating graphics, and completes updating graphics.

bubbles composed cancelable

Type definitions

RelativePosition

Type definition
Since
ArcGIS Maps SDK for JavaScript 5.2
Type
(typeof relativePositions)[number]

Variables

relativePositions

Variable
Type
readonly [ "bottom-end", "bottom-start", "bottom-left", "bottom-right", "top-end", "top-start", "top-left", "top-right" ]