▾
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
| Property | Attribute | Type |
|---|---|---|
| active-create-tool-draw-mode | ||
| | ||
| | ||
| readonly | | |
| | ||
| | ||
| auto-destroy-disabled | ||
| | CreateTool[] | undefined | |
| readonly | | |
| creation-mode | ||
| | ||
| default-graphics-layer-disabled | ||
| | ||
| readonly | | |
| 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 | ||
| deprecated | use-legacy-create-tools | |
| use-view-options | ||
| | ||
| | ||
| visual-scale | Button["scale"] |
activeCreateToolDrawMode
- 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
- 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
- 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
- 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
- Since
- ArcGIS Maps SDK for JavaScript 5.2
The tooltip currently being displayed for activeTool.
Returns null when no tooltip is visible.
activeVertexSymbol
- 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
- 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
- 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"]
creationMode
- 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
- Type
- CreateOptions
Default create options set for the Sketch component. Options passed to create() override these defaults for that operation.
defaultGraphicsLayerDisabled
- 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
- 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 operationsconst sketch = document.querySelector("arcgis-sketch");sketch.defaultUpdateOptions = {highlightOptions: {enabled: false}};// Override options for an individual update operationconst updateOptions = { tool: "reshape", highlightOptions: { enabled: false }};await sketch.triggerUpdate(graphic, updateOptions);
geometrySimplificationInProgress
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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"
labelOptions
- Type
- SketchLabelOptions
Options to configure the measurement labels shown next to each segment of the geometry being created or updated.
layer
- 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.
pointSymbol
- 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
- 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
- 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
- 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.
- Attribute
- reference-element
relativePosition
- 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"
showCreateToolsFreehandPolygon
- 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
- 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
- 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
- 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
- Type
- SnappingOptions
The SnappingOptions for sketching. It supports self and feature snapping.
These options are preserved but ignored while useViewOptions is true.
state
- Type
- SketchViewModel["state"]
The Sketch component's state.
| Value | Description |
|---|---|
| disabled | The component is not ready to create or update graphics. |
| ready | The component is ready to start an operation. |
| active | A create or update operation is in progress. |
textSymbol
- 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
- 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
- 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
- Type
- Collection<Graphic>
An array of graphics that are being updated by the Sketch component.
updateOnGraphicClickDisabled
- 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
- 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
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 5.2
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
nullorundefinedrestores 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
- 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
- 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
viewproperty 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 theviewproperty.
Methods
| Method | Signature |
|---|---|
| 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> |
cancel
- 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.
complete
- 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.
componentOnReady
- 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
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| 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. | |
- 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
- Signature
-
delete (): Promise<void>
Deletes the selected graphics used in the update workflow. Calling this method fires the @arcgisDelete event.
- Example
- sketch.addEventListener("arcgisDelete", (event) => {event.detail.graphics.forEach((graphic) => {console.log("Deleted graphic", graphic);});});await sketch.delete();
duplicate
- 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.
place
- 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
| Parameter | Type | Description | Required |
|---|---|---|---|
| geometry | Mesh geometry to place when creating the graphic. | |
- Example
- // create mesh at the global originconst 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 mouseawait sketch.place(box);// listen to create event, only respond when event's state changes to completesketch.addEventListener("arcgisCreate", function(event) {if (event.detail.state === "complete") {// retrieve the final position of the mesh which was chosen by the userconst mesh = event.detail.graphic.geometry;const placedLocation = mesh.origin;}});
removeAllGraphics
- 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.
removeGraphic
- 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.
removeGraphics
- 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.
triggerUpdate
- Signature
-
triggerUpdate (graphic: Parameters<SketchViewModel["update"]>[0], updateOptions?: Parameters<SketchViewModel["update"]>[1]): Promise<void>
Initializes an update operation for the specified graphic(s).
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| 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. | |
- 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});
Events
| Name | Type |
|---|---|
| CustomEvent<{ name: "activeTool" | "geometrySimplificationInProgress" | "state"; }> | |
arcgisCreate
arcgisCreate: CustomEvent<CreateEvent> Fires when a user starts sketching a graphic, is actively sketching a graphic and completes sketching a graphic.
arcgisDelete
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.
arcgisDuplicate
arcgisDuplicate: CustomEvent<DuplicateEvent> Fires when the user duplicates selected graphics.
arcgisPropertyChange
arcgisPropertyChange: CustomEvent<{ name: "activeTool" | "geometrySimplificationInProgress" | "state"; }> Emitted when the value of a property is changed. Use this to listen to changes to properties.
arcgisReady
arcgisReady: CustomEvent<void> Emitted when the component associated with a map or scene view is ready for user interaction.
arcgisRedo
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.
arcgisUndo
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.
arcgisUpdate
arcgisUpdate: CustomEvent<UpdateEvent> Fires when the user starts updating graphics, is actively updating graphics, and completes updating graphics.
Type definitions
RelativePosition
- Since
- ArcGIS Maps SDK for JavaScript 5.2
- Type
- (typeof relativePositions)[number]