RangeSlider

A RangeSlider can be used to select one or more values within a pre-defined range of available values.

RangeSlider with custom marks, tickbar, and value badges

Range

The RangeSlider control represents a range that is defined by the RangeStart and RangeEnd properties (where RangeStart is always the lesser of the two values). Each value has a thumb control that the end user can drag to change the value. Use the Minimum and Maximum properties to define the limits of the available range.

RangeSlider showing visual states for IsRanged and IsInclusive property value combinations

When the IsInclusive property is set to true (the default), the RangeSlider will show an indicator between the RangeStart and RangeEnd values to help visualize that the range includes all values in between. If the IsRangeDragEnabled property is set to true (the default value is false), the user can drag the indicator to move all thumbs at the same time. Set the IsInclusive property to false to hide the indicator.

If a range of values should always start at the Minimum, set the IsRanged property to false (the default value is true). When false, the RangeStart is locked to the same value as Minimum and a thumb control will not be displayed.

Step Frequency

The values defined by a RangeSlider are represented by the Double value type and can be any fractional value between Minimum and Maximum. However, most uses cases will want to limit the precision of values by setting the StepFrequency property to the smallest unit of change between two adjacent values on the slider.

Examples

For whole numbers, setting StepFrequency to 1.0 will adjust values to the nearest whole number while dragging.

For a non-fractional percentage (as a value from 0.00 to 1.00), set the StepFrequency to 0.01 so that each value, after being converted to a percentage, will represent a whole number (e.g., 0.25 becomes 25%).

For a range of very large numbers, it might be desirable to prevent selecting values that are too small. For example, if a slider control is being used to define the range of prices when searching for an expensive item like an automobile or house, it typically provides a better experience to adjust the value in larger intervals like 100, 1000, or even 10000 depending on the range of values.

Thumbs

An editable value on the slider is represented by a thumb control of type RangeSliderThumb.

RangeSlider showing with two thumbs showing a value badge

The user can drag the thumb to change the value. When the thumb has keyboard focus, the arrow keys will change the value by the SmallChange amount, and the PgDn/PgDn keys will change the value by the LargeChange amount.

Value Badge

Each thumb can display a value badge to help the user select the correct value.

The value badge is typically shown when the user is interacting with the thumb. The RangeSliderThumb.ValueBadgeDisplayKinds property (which is a flags enumeration) can be set to one or more of the following values to control when the badge is displayed:

• Always - The value badge is always displayed.
• None - The value badge is never displayed.
• Dragging - The value badge is shown when dragging the thumb.
• KeyboardFocused - The value badge is shown when the thumb has keyboard focus.
• PointerOver - The value badge is shown when the pointer is over the thumb.
• Interacting - (Default) A combination of Dragging, KeyboardFocused, and PointerOver. This is the default value.

The RangeSliderThumb.ValueBadgePlacement property is used to define the location of the Badge relative to the thumb and can be set to one of the following values:

• TopLeft - (Default) The badge is shown above the thumb when the slider is horizontally oriented and to the left of the thumb when the slider is vertically oriented. This is the default value.
• BottomRight - The badge is shown below the thumb when the slider is horizontally oriented and to the right of the thumb when the slider is vertically oriented.

Overlap

The OverlapKind property can be used to define the behavior when one thumb is dragged into another thumb. The following options are available:

• Overlap - (Default) Each thumb is allowed to overlap with other thumbs and can be dragged to any position on the slider. This is the default behavior.
• None - A thumb cannot overlap another thumb. If one thumb is dragged into another thumb, dragging will be stopped at the position of the other thumb.
• Push - A thumb cannot overlap another thumb. If one thumb is dragged into another thumb, the other thumb will be pushed in the same direction of the drag.

When OverlapKind is set to None or Push, it may be desirable to prevent the thumbs from having the same value. To limit how close one thumb may be dragged to another, set the MinimumStepsBetweenThumbs property to a value greater than 0. This property determines how many "steps" are between each thumb, and a "step" is defined by the StepFrequency property. For example, if a range slider is configured with MinimumStepsBetweenThumbs of 2 and a StepFrequency of 10, the values associated with the two thumbs cannot be closer than 20 (2 * 10 = 20).

Customizing

The RangeSlider.ThumbTheme property defines the ControlTheme which is applied to each RangeSliderThumb. Similarly, the RangeSliderThumb.ValueBadgeTheme property defines the ControlTheme which is applied to each Badge displayed by the thumb for the current value.

See the "Customizing Appearance" section below for examples of how to customize the ControlTheme of RangeSliderThumb in order to assign a custom ControlTheme for the value Badge.

Ticks

Ticks indicate specific, meaningful values within the range of the slider, helping users understand the scale and select appropriate values.

Use the TickPlacement property to specify if a TickBar should be displayed before and/or after the slider to provide visual guidance to the user about the specific tick values.

Ticks are defined using either the TickFrequency property or Ticks property. If the Ticks property is defined, the TickFrequency property is ignored.

RangeSlider with minimum-maximum range of 0-100 showing two different techniques for ticks

TickFrequency

The TickFrequency property is used to define intervals within the slider's minimum-maximum range where ticks will be placed. The first tick will be implied from the Minimum value. Then a tick will be placed at every interval defined by TickFrequency until the last tick which, is implied from the Maximum value.

In the following example, a slider is defined with a minimum-maximum range of 0-100 and a tick interval of 25, so ticks will be placed at 0, 25, 50, 75 and 100:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RangeSlider Minimum="0" Maximum="100" TickFrequency="25" ... />

Ticks Collection

The Ticks collection property can be used to define ticks that do not appear at fixed intervals. The first and last tick will be implied from the Minimum and Maximum values, respectively. The remaining ticks will correspond to the values explicitly defined in the collection.

In the following example, a slider is defined with a minimum-maximum range of 0-100 and explicit ticks at 20 and 80, so ticks will be placed at 0, 20, 80, and 100:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RangeSlider Minimum="0" Maximum="100" Ticks="20, 80" ... />

Marks

RangeSlider with minimum-maximum range of 0-100 showing marks at 0, 50, and 100

A mark, defined by RangeSliderMark, is similar to a tick since it is used to define a specific, meaningful value within the range of the slider. Unlike ticks, however, each mark has its own decoration on the slider's track and can include adjacent content (like a label or glyph) to help further define the significance of the value.

Marks are defined using either the Marks property or MarkElements property. If the MarkElements property is defined, the Marks property is ignored.

Marks Collection

The Marks collection property is used to define explicit values for one or more marks and is preferred when each mark can be displayed using default properties. Each value will be represented by an individual RangeSliderMark element whose Value corresponds to the defined value.

In the following example for a temperature range based on the Celsius scale, ticks are placed every 10 degrees and marks are placed at 0 and 100 to denote the freezing and boiling points of water:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RangeSlider Minimum="-50" Maximum="200" StepFrequency="1" TickFrequency="10" Marks="0, 100" ... />

MarkElements Collection

The MarkElements collection property is used to define one or more RangeSliderMark elements that will be displayed on the slider. This method is used when the individual elements require additional configuration beyond just the Value property.

Some important properties of RangeSliderMark include:

In the following example for a temperature range based on the Celsius scale, ticks are placed every 10 degrees and marks are placed at 0 and 100 to denote the freezing and boiling points of water with custom content and colors for each mark:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
xmlns:actiproPrimitives="using:ActiproSoftware.UI.Avalonia.Controls.Primitives"
...
<actipro:RangeSlider Minimum="-50" Maximum="200" StepFrequency="1" TickFrequency="10" ... >
	<actipro:RangeSlider.MarkElements>
		<actiproPrimitives:RangeSliderMark Value="0" Content="0&#176;C (Freezing)" Foreground="Blue" BorderBrush="Blue" />
		<actiproPrimitives:RangeSliderMark Value="100" Content="100&#176;C (Boiling)" Foreground="Red" BorderBrush="Red" />
	</actipro:RangeSlider.MarkElements>
</actipro:RangeSlider>

Snapping Values

Snapping is a feature that alters the value of a thumb to the nearest snap point while it is being moved. At the most basic level, snapping is enabled by setting the StepFrequency to a value greater than 0. For example, setting the StepFrequency to 1 will ensure that the value of the thumb is always moved to the nearest whole number.

When ticks are defined (see "Ticks" section above), setting IsSnapToTickEnabled will snap the thumb to the nearest tick. Snapping to ticks will override snapping to StepFrequency.

Snapping to Marks

One or more marks (see "Marks" section above) can also be configured as a snap point, and they operate independently from the other snap settings. Set the RangeSliderMark.SnapDistance to a value greater than 0 to enable snapping to the mark. If the non-inclusive differential of the thumb value and the mark value is within the snap distance, the thumb will be snapped to the mark. This can be used to "pull" the thumb to the mark when it gets close and can help the user select significant values.

For example, consider a slider whose StepFrequency is 1 that also has a RangeSliderMark whose Value is 5 and whose SnapDistance is 2. The StepFrequency of 1 indicates that as a thumb moves it is snapped to the nearest whole number. If the thumb is dragged from 0 it will snap to 1, 2, and 3 before jumping to 5. Since the mark has a value of 5 and a snap distance of 2, that means any value greater than 3 and less than 7 will snap to the mark value of 5.

Multiple Values

RangeSlider with three values

A range slider typically defines just two values, each defined by the RangeStart and RangeEnd properties. When more values are desired, the Values collection property can be used to define zero or more values. A thumb will be added for each value, and values can be added/removed from the collection at any time.

When IsRangeEditEnabled is set to true, the user will be able to add or remove values at runtime by holding the Ctrl key when clicking on the control. If the user clicks on an existing thumb, the thumb and its value will be removed. If the user clicks on an area where there is no thumb, a new thumb and value will be added that correspond to the click point. The Ins and Del keys can also be used to add or remove thumbs, respectively. Use the RangeEditMinimumValueCount and RangeEditMaximumValueCount properties to limit how many values the user can add/remove.

When using the Values collection, the RangeStart and RangeEnd properties will still reflect the smallest and largest values in the collection, respectively. If RangeStart is assigned a new value, every value in the collection that is less than the new value will be increased to the new start value. Similarly, if RangeEnd is assigned a new value, every value in the collection that is greater than the new value will be decreased to the new end value. Since this can result in multiple thumbs having the same value, it is recommended to treat RangeStart and RangeEnd as read-only properties (and use OneWay bindings) when working with multiple values.

The following example shows a range slider that is bound to a collection of Double values defined on the default DataContext and is configured to allow the user to define between 1 and 5 values.

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RangeSlider
	IsRangeEditEnabled="True"
	RangeEditMinimumValueCount="1"
	RangeEditMaximumValueCount="5"
	Values="{Binding SomeProperty}"
	...
	/>

Themes and Semantic Color Variants

RangeSlider in the outline and solid themes showing neutral and semantic color variants

The range slider control supports the accent, success, warning, and danger style class names for semantic variants.

The following control themes are also supported:

• RangeSliderBase - Base control theme used by several others.
• RangeSliderOutline (theme-outline) - Has an outline appearance.
• RangeSliderSolid (theme-solid) - Has a solid appearance.

The following example demonstrates how to define a range slider using the outline theme and accent variant:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RangeSlider Classes="theme-outline accent" />

String Formatting

Value badges and marks can display their corresponding value. The ValueFormat property can be used to specify any valid numeric or composite string format for the values.

Standard .NET numeric formats are supported. The following are some examples of string formatting (based on en-us culture):

Reverse Direction

RangeSlider with a minimum-maximum range of 0-100 in multiple orientations showing default and reversed directions with a selected range of 0 to 50

By default, a horizontal slider increases values from left-to-right, and a vertical slider increases values from bottom-to-top.

Set the IsDirectionReversed property to true to reverse the direction. When reversed, a horizontal slider increases values from right-to-left, and a vertical slider increases values from top-to-bottom.

Track Edge Alignment

RangeSlider with visible ticks and marks showing different track edge alignments

By default, the slider track is stretched to fill the available space. When a thumb is positioned at the minimum or maximum value on the track, the outside edge of the thumb will align with the outside edge of the track. This helps maintain consistent visual margins but does mean the edges of the track won't align with the same position as the minimum or maximum value. If ticks or marks are not displayed at the edges, this difference is imperceptible.

When ticks or marks are also displayed, it becomes obvious that the track edges extend beyond the position of the minimum and maximum values. If this look is undesirable, set IsTrackEdgeAlignedWithValue to true and the edges of the track will align with the position of the value at the edge, including any ticks or marks with the same value.

Customize Appearance

The ControlTheme of the RangeSliderMark, RangeSliderThumb (including the value Badge ), and TickBar can be updated to customize the appearance of the respective element.

RangeSliderMark

The RangeSlider.MarkTheme property is used to assign the default ControlTheme applied to all RangeSliderMark elements.

The following default control themes are available:

• RangeSliderMarkBase - Base control theme used by several others.
• RangeSliderMarkOutline (theme-outline) - Has an outline appearance.
• RangeSliderMarkSolid (theme-solid) - Has a solid appearance.

The default ControlTheme for RangeSlider will automatically update the MarkTheme property to correspond to the appearance of the slider (e.g., the RangeSliderOutline theme will use the RangeSliderMarkOutline theme).

If a specific theme is desired, set the MarkTheme to the desired ControlTheme. The following example shows how a ControlTheme for a solid appearance mark can be used on a slider with an outline appearance:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RangeSlider Classes="theme-outline" MarkTheme="{actipro:ControlTheme RangeSliderMarkSolid}" ... />

The following example extends the previous example to include setting additional properties:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
xmlns:actiproPrimitives="using:ActiproSoftware.UI.Avalonia.Controls.Primitives"
...

<actipro:RangeSlider Classes="theme-outline" ... >
	<actipro:RangeSlider.MarkTheme>
		<ControlTheme TargetType="actiproPrimitives:RangeSliderMark" BasedOn="{actipro:ControlTheme RangeSliderMarkSolid}">
			<Setter Property="Background" Value="White" />
			<Setter Property="Padding" Value="12" />
		</ControlTheme>
	</actipro:RangeSlider.MarkTheme>
</actipro:RangeSlider>

If the MarkTheme property is explicitly assigned like in the previous examples, the theme is no longer synchronized with the theme of the slider. To customize the theme without replacing the ControlTheme, a Style can be used instead. The following example shows how to use a Style to change the padding of all marks and the foreground color of active marks:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
xmlns:actiproPrimitives="using:ActiproSoftware.UI.Avalonia.Controls.Primitives"
...

<actipro:RangeSlider Classes="theme-outline" ... >
	<actipro:RangeSlider.Styles>
		<Style Selector="actiproPrimitives|RangeSliderMark">
			<Setter Property="Padding" Value="12" />
			<Style Selector="^:active">
				<Setter Property="Foreground" Value="Green" />
			</Style>
		</Style>
	</actipro:RangeSlider.Styles>
</actipro:RangeSlider>

RangeSliderThumb and Value Badge

The RangeSlider.ThumbTheme property is used to assign the default ControlTheme applied to all RangeSliderThumb elements.

The following default control themes are available:

• RangeSliderThumbBase - Base control theme used by several others.
• RangeSliderThumbOutline (theme-outline) - Has an outline appearance.
• RangeSliderThumbSolid (theme-solid) - Has a solid appearance.

The default ControlTheme for RangeSlider will automatically update the ThumbTheme property to correspond to the appearance of the slider (e.g., the RangeSliderOutline theme will use the RangeSliderThumbOutline theme).

If a specific theme is desired, set the MarkTheme to the desired ControlTheme. The following example shows how a ControlTheme for a solid appearance thumb can be used on a slider with an outline appearance:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RangeSlider Classes="theme-outline" ThumbTheme="{actipro:ControlTheme RangeSliderThumbSolid}" ... />

The following example extends the previous example to include setting additional properties:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
xmlns:actiproPrimitives="using:ActiproSoftware.UI.Avalonia.Controls.Primitives"
...

<actipro:RangeSlider Classes="theme-outline" ... >
	<actipro:RangeSlider.ThumbTheme>
		<ControlTheme TargetType="actiproPrimitives:RangeSliderThumb" BasedOn="{actipro:ControlTheme RangeSliderThumbSolid}">
			<Setter Property="Background" Value="Orange" />
		</ControlTheme>
	</actipro:RangeSlider.ThumbTheme>
</actipro:RangeSlider>

If the ThumbTheme property is explicitly assigned like in the previous examples, the theme is no longer synchronized with the theme of the slider. To customize the theme without replacing the ControlTheme, a Style can be used instead. The following example shows how to change the background color of thumb using a Style:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
xmlns:actiproPrimitives="using:ActiproSoftware.UI.Avalonia.Controls.Primitives"
...

<actipro:RangeSlider Classes="theme-outline" ... >
	<actipro:RangeSlider.Styles>
		<Style Selector="actiproPrimitives|RangeSliderThumb">
			<Setter Property="Foreground" Value="Green" />
		</Style>
	</actipro:RangeSlider.Styles>
</actipro:RangeSlider>

The ControlTheme of a value badge is specified by RangeSliderThumb.ValueBadgeTheme. Using either a ControlTheme or a Style, the Badge used to show the thumb value can be customized.

The following example uses a Style to customize the Badge:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
xmlns:actiproPrimitives="using:ActiproSoftware.UI.Avalonia.Controls.Primitives"
...

<actipro:RangeSlider Classes="theme-outline" ... >
	<actipro:RangeSlider.Styles>
		<Style Selector="actiproPrimitives|RangeSliderThumb">
			<Setter Property="ValueBadgeTheme">
				<ControlTheme TargetType="actipro:Badge" BasedOn="{actipro:ControlTheme BadgeSolid}">
					<Setter Property="FontSize" Value="{actipro:ThemeResource DefaultFontSizeMedium}" />
					<Setter Property="Padding" Value="5,2" />
					<Setter Property="BorderThickness" Value="0" />
					<Setter Property="Foreground" Value="{actipro:ThemeResource ControlForegroundBrushSolidAccent}" />
					<Setter Property="Background" Value="{actipro:ThemeResource ControlBackgroundBrushSolidAccent}" />
				</ControlTheme>
			</Setter>
		</Style>
	</actipro:RangeSlider.Styles>
</actipro:RangeSlider>

TickBar

The RangeSlider.TickBarTheme property is used to assign the ControlTheme applied to the TickBar elements used by the slider. The RangeSlider.TickPlacement property will update the TickBar.Placement property, as appropriate, and this property can be used to determine the position of the tickbar.

The following example demonstrates a custom ControlTheme for TickBar:

xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui"
...
<actipro:RangeSlider Orientation="Horizontal" TickPlacement="TopLeft" ... >
	<actipro:RangeSlider.TickBarTheme>
		<ControlTheme TargetType="TickBar" BasedOn="{actipro:ControlTheme RangeSliderTickBar}">
			<Style Selector="^[Placement=Top]">
				<Setter Property="Margin" Value="0,0,0,-10" />
				<Setter Property="Height" Value="15" />
			</Style>
			<Style Selector="^[Placement=Bottom]">
				<Setter Property="Margin" Value="0,-10,0,0" />
				<Setter Property="Height" Value="15" />
			</Style>
			<Style Selector="^[Placement=Left]">
				<Setter Property="Margin" Value="0,0,-10,0" />
				<Setter Property="Width" Value="15" />
			</Style>
			<Style Selector="^[Placement=Right]">
				<Setter Property="Margin" Value="-10,0,0,0" />
				<Setter Property="Width" Value="15" />
			</Style>
		</ControlTheme>
	</actipro:RangeSlider.TickBarTheme>
</actipro:RangeSlider>

Pseudo-classes

The following pseudo-classes are available for RangeSlider and can be used when styling the control:

The following pseudo-classes are available for RangeSliderMark and can be used when styling the control:

The following pseudo-classes are available for RangeSliderThumb and can be used when styling the control: