Skip to content

Grid Controls

ESM:
Use dark colors for code blocksCopy
1
import "@arcgis/map-components/components/arcgis-grid-controls";
CDN:
No specific import is needed for this component.

The Grid Controls component provides a user interface (UI) for configuring and displaying a two-dimensional grid. The grid displayed provides a network of horizontal and vertical lines used to divide the view into equal cells. With support for snapping, the grid lines can be used as a reference when drawing features. Note: grid controls are embedded in snapping controls for Sketch and Editor by default.

Known limitations

  • Grid Controls is only supported in a 2D Map component.
  • The grid spacing does not correspond to real world measurements. Distortion will be minimized when used in conjunction with an equal area basemap.
  • The grid spacing input will be hidden when working with Web Mercator and Geographic Coordinate Systems.

Demo

Properties

PropertyAttributeType
autoDestroyDisabledauto-destroy-disabledboolean
customColor
reflected
custom-colorColor
boolean
dynamicScalingdynamic-scalingboolean
effective-spacing-after-dynamic-scalingnumber
gridColor
reflected
grid-colorColor
boolean
gridOutOfScale
readonlyreflected
grid-out-of-scaleboolean
hideColorSelectionhide-color-selectionboolean
hideDynamicScaleTogglehide-dynamic-scale-toggleboolean
hideGridEnabledTogglehide-grid-enabled-toggleboolean
hideGridSnapEnabledTogglehide-grid-snap-enabled-toggleboolean
hideLineIntervalInputhide-line-interval-inputboolean
hideNumericInputshide-numeric-inputsboolean
hideOutOfScaleWarninghide-out-of-scale-warningboolean
hidePlacementButtonshide-placement-buttonsboolean
hideRotateWithMapTogglehide-rotate-with-map-toggleboolean
iconiconstring
interactive-placement-state"interactive" | "place" | "rotate"
labellabelstring
major-line-intervalnumber
messageOverridesRecord<string, unknown>
placementDisabledplacement-disabledboolean
position
deprecatedreflected
position"bottom-leading" | "bottom-left" | "bottom-right" | "bottom-trailing" | "manual" | "top-leading" | "top-left" | "top-right" | "top-trailing"
referenceElementreference-elementHTMLArcgisLinkChartElement | HTMLArcgisMapElement | HTMLArcgisSceneElement | string
rotateWithMaprotate-with-mapboolean
rotation
reflected
rotationnumber
snappingEnabledsnapping-enabledboolean
snappingOptionsSnappingOptions
spacing
reflected
spacingnumber
themetheme"custom" | "dark" | "light"
unitunit"centimeters" | "decimeters" | "feet" | "inches" | "kilometers" | "meters" | "miles" | "millimeters" | "nautical-miles" | "us-feet" | "yards"
viewMapView

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

customColor

reflected
Property
customColor: Color

The custom color used for drawing the grid, if any.

Attribute
custom-color

displayEnabled

readonlyProperty
displayEnabled: boolean

Returns true if the grid is enabled for display. Use trySetDisplayEnabled to enable or disable grid display.

Default value
false

dynamicScaling

Property
dynamicScaling: boolean

Returns true if the grid is set to scale dynamically. When dynamic scaling is enabled, grid cells are added or removed to ensure that grid cells are a reasonable size on screen as the user zooms. The way additional grid lines are shown is controlled by the majorLineInterval property.

Attribute
dynamic-scaling
Default value
false

effectiveSpacingAfterDynamicScaling

readonlyreflected
Property
effectiveSpacingAfterDynamicScaling: number

Returns the actual spacing of grid lines after dynamic scaling has been applied at the current scale.

Attribute
effective-spacing-after-dynamic-scaling

gridColor

reflected
Property
gridColor: Color

Controls the color of the major grid lines. Minor grid lines are a slightly transparent version of this color.

Attribute
grid-color

gridControlsEnabled

readonlyProperty
gridControlsEnabled: boolean

Returns true if the grid is in a valid state for manually setting grid properties or starting an interactive placement.

Default value
false

gridOutOfScale

readonlyreflected
Property
gridOutOfScale: boolean

True if the grid is currently not displayed (and therefore also not a valid snap target), because dynamicScaling is off and the grid cells are too small to render at the current scale.

Attribute
grid-out-of-scale
Default value
false

hideColorSelection

Property
hideColorSelection: boolean

Controls display of the color and theme selection options.

Attribute
hide-color-selection
Default value
false

hideDynamicScaleToggle

Property
hideDynamicScaleToggle: boolean

Controls display of the dynamic scaling toggle. Dynamic scaling adjusts the size of the grid to work well regardless of view scale.

Attribute
hide-dynamic-scale-toggle
Default value
false

hideGridEnabledToggle

Property
hideGridEnabledToggle: boolean

Controls display of the grid enabled toggle. This toggle controls whether the grid is displayed.

Attribute
hide-grid-enabled-toggle
Default value
false

hideGridSnapEnabledToggle

Property
hideGridSnapEnabledToggle: boolean

Controls display of the grid snapping enabled toggle. This toggle controls whether snapping is enabled.

Attribute
hide-grid-snap-enabled-toggle
Default value
false

hideLineIntervalInput

Property
hideLineIntervalInput: boolean

Controls display of the line interval input field for setting the interval between major grid lines.

Attribute
hide-line-interval-input
Default value
false

hideNumericInputs

Property
hideNumericInputs: boolean

Controls display of the numeric input fields for setting grid spacing and rotation.

Attribute
hide-numeric-inputs
Default value
false

hideOutOfScaleWarning

Property
hideOutOfScaleWarning: boolean

Controls display of the out of scale warning. This warning is displayed when the grid is not shown because it would be too small at the current scale and dynamic scaling is disabled.

Attribute
hide-out-of-scale-warning
Default value
false

hidePlacementButtons

Property
hidePlacementButtons: boolean

Controls display of the grid placement buttons. These buttons allow the user to start interactive configuration of the grid.

Attribute
hide-placement-buttons
Default value
false

hideRotateWithMapToggle

Property
hideRotateWithMapToggle: boolean

Controls display of the rotate with map toggle. This toggle controls whether the grid rotates with the map.

Attribute
hide-rotate-with-map-toggle
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
Attribute
icon
Default value
"grid-unit"

interactivePlacementState

reflected
Property
interactivePlacementState: "interactive" | "place" | "rotate"

Sets the interactive placement state, either starting or ending a draw operation that implicitly adjusts the grid. Interactive placement allows the user to define the center of the grid, then the scale and rotation of the grid by drawing a second point. Setting this to "place" allows the user to move the grid center only. Setting this to "rotate" keeps the scale and center of the grid constant while rotating the grid by defining a second point.

Attribute
interactive-placement-state
Default value
null

label

Property
label: string

The component's default label.

Attribute
label

majorLineInterval

reflected
Property
majorLineInterval: number

Controls the number of grid cells shown between major grid lines. Can be anything between 1 and 15. No minor grid lines are shown when this is set to 1.

Attribute
major-line-interval
Default value
10

messageOverrides

Property
messageOverrides: Record<string, unknown>

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

placementDisabled

Property
placementDisabled: boolean

Use this property to disable the interactive grid placement buttons as needed. An example use case might be to block interaction while another interactive operation (e.g. sketching) is in progress.

Attribute
placement-disabled
Default value
false

position

deprecatedreflected
Property
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

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

rotateWithMap

Property
rotateWithMap: boolean

Controls whether the grid rotates with the map, or stays fixed to the screen.

Attribute
rotate-with-map
Default value
true

rotation

reflected
Property
rotation: number

Rotation of the grid in radians. NOTE: UI controls convert to and from degrees automatically.

Attribute
rotation

snappingEnabled

Property
snappingEnabled: boolean

Controls snapping behavior if snappingOptions has been defined. If snappingOptions have been defined, disabling or enabling grid snapping will also disable or enable grid display.

Attribute
snapping-enabled
Default value
false

snappingOptions

Property
snappingOptions: SnappingOptions

The SnappingOptions that will be controlled by this component if the snapping toggle is enabled for display. If SnappingOptions are provided, grid display will be automatically enabled or disabled to match snapping state.

spacing

reflected
Property
spacing: number

Length of a grid cell. Grid cells are always square. Defined in unit.

Attribute
spacing
Default value
1

theme

Property
theme: "custom" | "dark" | "light"

The color scheme used to display the grid. This will be light, dark, or custom. When theme is set to custom, the customColor is shown, otherwise a default light or dark theme color is used.

Attribute
theme
Default value
"dark"

unit

Property
unit: "centimeters" | "decimeters" | "feet" | "inches" | "kilometers" | "meters" | "miles" | "millimeters" | "nautical-miles" | "us-feet" | "yards"

Unit of measure (foot, meter, etc) used when defining the spacing grid cell. Note that units are defined relatively to the map's spatial reference length unit, which will not correspond to geographic distance unless using a special-purpose basemap within a supported target area.

When using Web Mercator, the projection defines the length of a meter in projection system units; this length is equal to a geographic meter only at the equator. On screen, the size of the grid cells is constant from the equator to the poles, but the real-world size of the grid cell is much larger further from the equator.

The length of the grid cells can usefully correspond to a geographic length when the Grid is used with an appropriate spatial reference (for example a local system or a State Plane system) within the reference's area of interest.

Attribute
unit

view

Property
view: MapView

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

Methods

MethodSignature
componentOnReadycomponentOnReady(): Promise<void>
destroydestroy(): Promise<void>
trySetDisplayEnabledtrySetDisplayEnabled(enabled: boolean): void

componentOnReady

Method
componentOnReady(): Promise<void>

Create a promise that resolves once component is fully loaded.

Example
Use dark colors for code blocksCopy
1
2
3
4
const arcgisGridControls = document.querySelector("arcgis-grid-controls");
document.body.append(arcgisGridControls);
await arcgisGridControls.componentOnReady();
console.log("arcgis-grid-controls is ready to go!");
Returns
Promise<void>

destroy

Method
destroy(): Promise<void>

Permanently destroy the component.

Returns
Promise<void>

trySetDisplayEnabled

Method
trySetDisplayEnabled(enabled: boolean): void

Call this to turn the grid on/off.

Parameters
ParameterTypeOptional?
enabledboolean
Returns
void

Events

EventType
arcgisPropertyChangeCustomEvent<{ name: "rotation" | "theme" | "customColor" | "rotateWithMap" | "spacing" | "majorLineInterval" | "gridColor" | "displayEnabled" | "gridOutOfScale" | "dynamicScaling" | "gridControlsEnabled" | "interactivePlacementState" | "snappingEnabled" | "effectiveSpacingAfterDynamicScaling"; }>
arcgisReadyCustomEvent<void>

arcgisPropertyChange

Event
arcgisPropertyChange: CustomEvent<{ name: "rotation" | "theme" | "customColor" | "rotateWithMap" | "spacing" | "majorLineInterval" | "gridColor" | "displayEnabled" | "gridOutOfScale" | "dynamicScaling" | "gridControlsEnabled" | "interactivePlacementState" | "snappingEnabled" | "effectiveSpacingAfterDynamicScaling"; }>

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 to be interacted with.

bubbles
composed
cancelable

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.