arcgis-slider-histogram-range | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/common-components/components/arcgis-slider-histogram-range";

Inheritance: ArcgisSliderHistogramRange→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

A slider component with a histogram that can be used for filtering data. This component uses its fieldType property to support numeric and temporal datasets, where values associated with a given fieldType are parsed into numbers that can be used for rendering the histogram and slider. Those values are then serialized back into strings for component properties and readable labels. Much of this work can be done by the component so the user does not have to manually set component properties. The resulting object from passing the target layer and field to the histogram() and summaryStatistics() functions can be passed to the updateFromHistogramResult() method to automatically set the component's bins, average, and standardDeviation properties, as well as set the min and max bounds for the component.

Note that when setting properties manually (such as setting the value property to place thumbs on the slider), the component expects the inputs to match the format that would be expected by the fieldType. Below are a few relevant examples

See also

Demos

Example

// fieldType === "double"
histogramSlider.value = "20.5, 75.25";

// fieldType === "date"
histogramSlider.value = "1710028800000, 1726617600000";

// fieldType === "date-only"
histogramSlider.value = "2024-03-10, 2024-09-18";

// fieldType === "time-only"
histogramSlider.value = "08:15:00, 17:45:00";

// fieldType === "timestamp-offset"
histogramSlider.value = "2024-03-10T08:00:00-05:00, 2024-09-18T18:30:00-05:00";

See the image below for a summary of the configurable options available on this slider.

HistogramRangeSlider with annotations

Properties

Property	Attribute	Type
activeValue readonly		string \| undefined
average	average	number \| undefined
bins		HistogramBin[] \| undefined
dataLines		DataLine[] \| undefined
excludedBarColor		Color \| undefined
fieldType	field-type	FieldSliderType
fillPlacement	fill-placement	"between" \| "end" \| "none" \| "not-between" \| "start"
includedBarColor		Color \| undefined
label	label	string \| undefined
labelFormatter		LabelFormatter \| undefined
layout	layout	"horizontal" \| "vertical"
max	max	string \| undefined
min	min	string \| undefined
rangeLabelsEditingEnabled	range-labels-editing-enabled	boolean
rangeLabelsPlacement	range-labels-placement	ArcgisSlider["rangeLabelsPlacement"]
showRangeLabels	show-range-labels	boolean
standardDeviation	standard-deviation	number \| undefined
standardDeviationCount	standard-deviation-count	number
value	value	string \| undefined
valueLabelsDisplay	value-labels-display	ArcgisSlider["valueLabelsDisplay"]
valueLabelsEditingEnabled	value-labels-editing-enabled	boolean

activeValue

readonly Property

Type: string | undefined

The active value of the component, based on which thumb or range (segment) is active. This returns the stored value for the active thumb, so it may reflect the thumb’s last set position.

It returns:

undefined when no value is active
a serialized string when a single value is active
"all" when the range (segment) is active

Listen to @arcgisActiveValueChange to be notified when a value becomes active or inactive.

average

Property

Type: number | undefined

The statistical average of the data in the histogram. You would typically get this value from the avg property of SummaryStatisticsResult, which is the result of the summaryStatistics function.

When set, this value will render on the histogram with a symbol indicating it is the average.

See also

summaryStatistics

Attribute: average

Example

// Uses the summaryStatistics() function to compute the average value of a field
const params = { layer, field: "POPULATION" };

const statistics = await summaryStatistics(params);

histogramSlider.average = statistics.avg;

bins

Property

Type: HistogramBin[] | undefined

An array of objects representing each bin in the histogram. This information is typically returned from the histogram function.

See also

histogram

Examples

// Sets the bins of the histogram from the bins in the histogram() result
const params = { layer, field: "POPULATION" };

const histogramResult = await histogram(params);

await histogramSlider.updateFromHistogramResult(histogramResult);

// Creates a histogram with 7 bins.
histogramSlider.bins = [
  { minValue: 0, maxValue: 10, count: 4 },
  { minValue: 11, maxValue: 20, count: 14 },
  { minValue: 21, maxValue: 30, count: 9 },
  { minValue: 31, maxValue: 40, count: 34 },
  { minValue: 41, maxValue: 50, count: 351 },
  { minValue: 51, maxValue: 60, count: 100 },
  { minValue: 61, maxValue: 70, count: 1 }
];

dataLines

Property

Type: DataLine[] | undefined

Renders lines on the histogram that indicate important or meaningful values to the end user. Set the average and standardDeviation properties to display unique data lines for the mean and each standard deviation interval defined by standardDeviationCount.

Example

// Will render lines at the 25th, 50th, 75th, and 99th percentiles
histogramSlider.dataLines = [{
  value: 30,
  label: "25 pctl"
}, {
  value: 45,
  label: "50 pctl"
}, {
  value: 65,
  label: "75 pctl"
}, {
  value: 89,
  label: "99 pctl"
}];

excludedBarColor

Property

Type: Color | undefined

Sets the color of the histogram bars that are excluded based on the specified fillPlacement. For example, when a fillPlacement of between is used, all bars not between the slider thumbs will be rendered with the color set here.

To change the style of histogram bars representing included data based on the fillPlacement, use the includedBarColor property.

See also

Example

histogramSlider.excludedBarColor = "black";

fieldType

Property

Type: FieldSliderType

Defines the ArcGIS field type used to parse, format, and serialize slider values.

Supported values:

Numeric: small-integer, integer, big-integer, single, double, long, oid
Temporal: date, date-only, time-only, timestamp-offset

See also

Field.type

Attribute: field-type
Default value: "double"

fillPlacement

Property

Type: "between" | "end" | "none" | "not-between" | "start"

Controls where the filled segment is displayed on the slider track and histogram. Note that "between" and "not-between" will fall back to "start" if a single thumb slider is being used, and "start" and "end" will fall back to "between" for sliders with multiple thumbs.

See also

arcgis-slider.fillPlacement

Attribute: fill-placement
Default value: "start"

includedBarColor

Property

Type: Color | undefined

Sets the color of the histogram bars that are included based on the specified fillPlacement. For example, when a fillPlacement of between is used, all bars between the slider thumbs will be rendered with the color set here.

To change the style of histogram bars representing excluded data based on the fillPlacement, use the excludedBarColor property.

See also

Example

histogramSlider.includedBarColor = "green";

label

Property

Type: string | undefined

The component's default label.

Attribute: label

labelFormatter

Property

Type: LabelFormatter | undefined

A function used to format labels. Overrides the default label formatter.

See also

layout

Property

Type: "horizontal" | "vertical"

Determines the layout/orientation of the component. By default, the slider will render horizontally with the min value on the left side of the track.

Attribute: layout
Default value: "horizontal"

max

Property

Type: string | undefined

The maximum value or upper bound of the slider.

Attribute: max

min

Property

Type: string | undefined

The minimum value or lower bound of the slider.

Attribute: min

rangeLabelsEditingEnabled

Property

Type: boolean

When true, allows editing the min/max range labels with keyboard input.

Applies only to: small-integer, integer, big-integer, single, double, long, oid.

See also

arcgis-slider.rangeLabelsEditingEnabled

Attribute: range-labels-editing-enabled
Default value: false

rangeLabelsPlacement

Property

Type: ArcgisSlider["rangeLabelsPlacement"]

Controls where min/max range labels are positioned relative to the track.

See also

Attribute: range-labels-placement
Default value: "center"

showRangeLabels

Property

Type: boolean

Indicates whether min and max range labels are visible on the slider.

Attribute: show-range-labels
Default value: false

standardDeviation

Property

Type: number | undefined

The statistical standard deviation of the dataset. You would typically get this value from the stddev property of SummaryStatisticsResult, which is the result of the summaryStatistics function.

When set, multiples of this value will render on the histogram above and below the average with symbols indicating standard deviation intervals. The number of intervals rendered is determined by the standardDeviationCount property.

See also

summaryStatistics

Attribute: standard-deviation

standardDeviationCount

Property

Type: number

Indicates the number of standard deviation lines to render on the histogram from the arcgis-histogram.average.

Attribute: standard-deviation-count
Default value: 1

Example

// Will render lines for +σ, +2σ, +3σ, and -σ, -2σ, -3σ
histogramSlider.standardDeviationCount = 3;

value

Property

Type: string | undefined

A comma delimited string representing absolute thumb positions on the slider. Each value must match the current format expected by the component's fieldType property.

Attribute: value

Example

// fieldType === "double"
histogramSlider.value = "20.5, 75.25";

valueLabelsDisplay

Property

Type: ArcgisSlider["valueLabelsDisplay"]

Controls when thumb value labels are displayed.

"always": Always show labels.
"auto": Show labels only during interaction.
"hidden": Never show labels.

See also

arcgis-slider.valueLabelsDisplay

Attribute: value-labels-display
Default value: "always"

valueLabelsEditingEnabled

Property

Type: boolean

When true, allows editing value labels with keyboard input.

Applies only to: small-integer, integer, big-integer, single, double, long, oid.

See also

arcgis-slider.valueLabelsEditingEnabled

Attribute: value-labels-editing-enabled
Default value: false

Methods

Method	Signature
componentOnReady inherited	componentOnReady(): Promise<this>
destroy	destroy(): Promise<void>
generateWhereClause	generateWhereClause(field: string): Promise<string \| undefined>
updateFromHistogramResult	updateFromHistogramResult(histogramResult: HistogramResult, statistics?: SummaryStatisticsResult): 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 arcgisSliderHistogramRange = document.createElement("arcgis-slider-histogram-range");
document.body.append(arcgisSliderHistogramRange);
await arcgisSliderHistogramRange.componentOnReady();
console.log("arcgis-slider-histogram-range is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroys the component.

Returns: Promise<void>

generateWhereClause

Method

Signature: generateWhereClause (field: string): Promise<string | undefined>

Generates a SQL WHERE clause based on a given field and the slider's fillPlacement. This is a convenience function for data filtering or data queries. It is the user's responsibility to ensure that the type of the given field matches one of the available values of the component's fieldType.

Parameters

Parameter	Type	Description	Required
field	string

Returns: Promise<string | undefined>

Example

// Renders the component's histogram such that all bins between
// the two slider thumbs are shaded with a blue color by default
histogramSlider.fillPlacement = "between";

// Filters the FeatureLayerView such that only features with
// a particular field value that falls between the two slider thumbs are displayed
layerView.filter = {
  where: await histogramSlider.generateWhereClause("POPULATION")
}

Note: If a single thumb slider has its fillPlacement set to "between" or "not-between", the generated clause will use start instead. Additionally, if a multi thumb slider has its fillPlacement set to "start" or "end", the generated clause will use "between" instead.

updateFromHistogramResult

Method

Signature: updateFromHistogramResult (histogramResult: HistogramResult, statistics?: SummaryStatisticsResult): Promise<void>

A convenience function which allows the bins, min, max, average, and standardDeviation properties to be set automatically from the results of the histogram() and summaryStatistics() functions. The component will serialize these values based on the fieldType property into a format that is expected by the slider.

Parameters

Parameter	Type	Description	Required
histogramResult	HistogramResult
statistics	SummaryStatisticsResult

Returns: Promise<void>

Example

const histogramResult = await histogram({
  layer,
  field: "POPULATION",
  numBins: 30,
});

const statistics = await summaryStatistics({
  layer,
  field: "POPULATION",
});

await histogramSlider.updateFromHistogramResult(histogramResult, statistics);

Events

Name	Type
arcgisActiveValueChange	CustomEvent<void>
arcgisChange	CustomEvent<void>
arcgisInput	CustomEvent<void>
arcgisRangeChange	CustomEvent<void>

arcgisActiveValueChange

Event

arcgisActiveValueChange: CustomEvent<void>

Fires when the activeValue changes as a thumb or the range gains or loses focus. This event does not fire when value change. Use @arcgisInput for continuous updates or @arcgisChange when the interaction is committed.

See also

arcgis-slider.activeValue

arcgisChange

Event

arcgisChange: CustomEvent<void>

Fires when a thumb or range is released on the slider. Use @arcgisInput for continuous updates during a drag.

See also

arcgis-slider.@arcgisChange

arcgisInput

Event

arcgisInput: CustomEvent<void>

Fires continuously while the thumb or range is being dragged. This event can fire frequently; consider debouncing or throttling expensive work.

See also

arcgis-slider.@arcgisInput

arcgisRangeChange

Event

arcgisRangeChange: CustomEvent<void>

Fires when the slider's range changes. This occurs when the user edits the min or max range labels (when enabled).

See also

arcgis-slider.@arcgisRangeChange

Styles

Name	Default	Description
--arcgis-slider-histogram-range-histogram-height		Specifies the height of the histogram.

--arcgis-slider-histogram-range-histogram-height

Style

Specifies the height of the histogram.