Skip to content

Components/RangeSlider - #14

Open
Dover8 wants to merge 5 commits into
Unity-UI-Extensions:developmentfrom
Dover8:feature/RangeSlider
Open

Dover8 wants to merge 5 commits into
Unity-UI-Extensions:developmentfrom
Dover8:feature/RangeSlider

Conversation

@Dover8

@Dover8 Dover8 commented Nov 17, 2026 •

Copy link
Copy Markdown

Unity UI Toolkit Extensions - Pull Request

Overview

Adds RangeSlider, a UI Toolkit port of the uGUI Extensions RangeSlider (originally contributed via Dover8/Unity-UI-Extensions#1).
It's a two-handled horizontal slider that selects a low and a high value between a min and max, e.g. for filtering search results by price or size.

<ext:RangeSlider min-value="0" max-value="1000" low-value="250" high-value="750" whole-numbers="true" />
var priceFilter = new RangeSlider(minValue: 0, maxValue: 1000, lowValue: 250, highValue: 750, wholeNumbers: true);
priceFilter.OnValueChanged += (low, high) => UpdatePriceLabels(low, high);   // every change, incl. each pointer move
priceFilter.OnDragEnd += (low, high) => RunSearch(low, high);                // once, when a drag finishes
// or the standard UI Toolkit way:
priceFilter.RegisterValueChangedCallback(evt => UpdatePriceLabels(evt.newValue.x, evt.newValue.y));

Why not use UI Toolkit's MinMaxSlider?

UI Toolkit has a runtime MinMaxSlider (UnityEngine.UIElements, under Standard in the UI Builder library). It's a different control from IMGUI's editor-only EditorGUI.MinMaxSlider. It covers the basics, including dragging the whole range, but it falls short for filtering UIs like this one:

  • Float values only. It has no whole-number option and there's no integer version, so filters like price, bedrooms or year need rounding in user code. RangeSlider has whole-numbers, which snaps handle drags, range drags and keyboard steps.
  • Basic default look. It ships as a labelled form field with thin, editor-style thumbs. RangeSlider is a standalone control styled like the rest of this library, with round touch-friendly handles, and can be re-themed through --rangeSlider-* custom properties. It has no built-in label, so add a Label next to it if needed.
  • Same API as the uGUI version. RangeSlider keeps the uGUI Extensions names (MinValue/MaxValue/LowValue/HighValue, OnValueChanged(low, high)), which makes moving from the uGUI package easy. Like MinMaxSlider, it also raises ChangeEvent<Vector2>, so switching between the two is straightforward.

Changes

  • Runtime/Controls/RangeSlider/RangeSlider.cs - the new [UxmlElement] control (namespace UnityUIToolkit.Extensions).
    • Keeps the uGUI API: MinValue, MaxValue, LowValue, HighValue, WholeNumbers, NormalizedLowValue, NormalizedHighValue, SetValueWithoutNotify(low, high), OnValueChanged(low, high).
    • Interaction states follow the original (Low / High / Bar): drag a handle, or drag the fill to move the whole range.
    • Also implements INotifyValueChanged<Vector2>, so value, RegisterValueChangedCallback and bubbling ChangeEvent<Vector2> work like the built-in fields.
    • OnDragEnd(low, high) fires once when the user finishes a pointer drag that changed the range, so costly work like re-running a filter doesn't have to run on every pointer move. It isn't raised for taps, keyboard steps or changes from code.
    • Each handle has a 44px touch target around a 20px visible knob, matching the library's other tappable controls (PillInputField, PillSelector and ColorToggleButton are 44px). When two targets overlap, the nearer handle is picked.
    • UXML attributes: min-value, max-value, low-value, high-value, whole-numbers, step-size, snap-to-step.
  • Runtime/Styles/UIToolkitExtensionsControlStyles.uss - rangeSlider styles (BEM classes exposed as constants), themeable via --rangeSlider-* custom properties.
  • Editor/UIToolkitExtensionsMenuOptions.cs + Editor/ControlTemplates/RangeSliderStarter.uxml - GameObject/UI Toolkit/Extensions/Range Slider and Assets/Create/UI Toolkit/Extensions/Range Slider Starter.
  • CHANGELOG.md (new Unreleased section), README.md (control count 25 -> 26, and the namespace corrected from the uGUI package's Unity.UI.Extensions to UnityUIToolkit.Extensions), Documentation~ control list.

Behaviour changes compared with the uGUI version

  • Fixed: SetValueWithoutNotify(low, high) clamped the new low against the old high. For example, going from 10..12 to (20, 80) gave 12..80.
  • Fixed: a bar drag re-centred the range on the pointer (it jumped on the first move). It also moved low before high, so a fast drag could collapse the range. It now moves both ends by the drag distance and keeps the range size.
  • Fixed: when both handles overlapped at the max, only the high handle could be grabbed, so the range was stuck. Now the first drag direction decides which handle moves.
  • New: pressing the track outside the range jumps the nearest handle there and keeps dragging it. The original ignored these presses.
  • New: keyboard / gamepad support. Tab to a handle, then left/right steps it by StepSize (step-size in UXML). The default of 0 uses 1% of the range, rounded to a whole number of at least 1 when whole-numbers is on. Custom values are also rounded that way. The uGUI version left OnMove unimplemented. Its private StepSize (1 for whole numbers, otherwise 10%) moved too far without whole numbers and too little with them, so it isn't carried over.
  • New: SnapToStep (snap-to-step in UXML), off by default. When on, user input snaps to stops every StepSize from MinValue, and MaxValue is always a stop too. Handle drags and track presses go to the nearest stop, range drags move in whole steps, and keyboard steps go to the next stop. Values set from code or UXML are never snapped. It's a plain property, so it can be changed at runtime, e.g. from a user setting, and doing so doesn't move the current values.
  • New: if low/high sits on the min/max when that limit changes, it follows the new limit, so a full-range selection stays full. This also lets UXML set min-value/max-value then low-value/high-value without the values being clamped to the default 0..1 range first.

Follow-up work

  • A RangeSlider sample scene for the Examples repo (com.unity.uitoolkitextensions.examples), e.g. a property-search filter, with both a C# and a UXML version like the existing samples.
  • A RangeSlider page for the UI Toolkit controls documentation.

Breaking Changes

  • None. This only adds a new control.

Related Submodule Changes

  • None yet. The Examples sample is listed under Follow-up work.

Testing status

  • No tests have been added (the package has no test assembly yet).
  • Outside the repo, the value and interaction logic was checked against a line-by-line model: 79 scenarios plus randomised checks that values always stay within the limits and the handles never cross.

Manual testing status

Tested in the Unity 6 Editor:

  • UI Builder: the starter template renders, with handles at the expected positions, so the UXML attributes are applied. It was also checked side by side with the built-in MinMaxSlider.
  • Play Mode, using a test scene with low / high labels and a snap toggle:
    • labels update through OnValueChanged, and ChangeEvent<Vector2> fires once per change;
    • dragging handles and the range, pressing the track, and overlapping handles;
    • handle touch targets at the track ends and with handles close together;
    • OnDragEnd fires once per drag that changed the range, and not for taps;
    • keyboard stepping with the default and a custom step-size, with whole-numbers on and off;
    • snap-to-step switched at runtime.

# Unity UI Toolkit Extensions - Pull Request

## Overview

Adds **RangeSlider**, a UI Toolkit port of the uGUI Extensions `RangeSlider` (originally contributed via [Dover8/Unity-UI-Extensions#1](Dover8/Unity-UI-Extensions#1)).
It's a two-handled horizontal slider that selects a low and a high value between a min and max, e.g. for filtering search results by price or size.

```xml
<ext:RangeSlider min-value="0" max-value="1000" low-value="250" high-value="750" whole-numbers="true" />
```

```csharp
var priceFilter = new RangeSlider(minValue: 0, maxValue: 1000, lowValue: 250, highValue: 750, wholeNumbers: true);
priceFilter.OnValueChanged += (low, high) => ApplyPriceFilter(low, high);
// or the standard UI Toolkit way:
priceFilter.RegisterValueChangedCallback(evt => ApplyPriceFilter(evt.newValue.x, evt.newValue.y));
```

### Why not use UI Toolkit's `MinMaxSlider`?

UI Toolkit has a runtime `MinMaxSlider` (`UnityEngine.UIElements`, under *Standard* in the UI Builder library). It's a different control from IMGUI's editor-only `EditorGUI.MinMaxSlider`. It covers the basics, including dragging the whole range, but it falls short for filtering UIs like this one:

- **Float values only.** It has no whole-number option and there's no integer version, so filters like price, bedrooms or year need rounding in user code. RangeSlider has `whole-numbers`, which snaps handle drags, range drags and keyboard steps.
- **Basic default look.** It ships as a labelled form field with thin, editor-style thumbs. RangeSlider is a standalone control styled like the rest of this library, with round touch-friendly handles, and can be re-themed through `--rangeSlider-*` custom properties. It has no built-in label, so add a `Label` next to it if needed.
- **Same API as the uGUI version.** RangeSlider keeps the uGUI Extensions names (`MinValue`/`MaxValue`/`LowValue`/`HighValue`, `OnValueChanged(low, high)`), which makes moving from the uGUI package easy. Like `MinMaxSlider`, it also raises `ChangeEvent<Vector2>`, so switching between the two is straightforward.

## Changes

- `Runtime/Controls/RangeSlider/RangeSlider.cs` - the new `[UxmlElement]` control (namespace `UnityUIToolkit.Extensions`).
  - Keeps the uGUI API: `MinValue`, `MaxValue`, `LowValue`, `HighValue`, `WholeNumbers`, `NormalizedLowValue`, `NormalizedHighValue`, `SetValueWithoutNotify(low, high)`, `OnValueChanged(low, high)`.
  - Interaction states follow the original (Low / High / Bar): drag a handle, or drag the fill to move the whole range.
  - Also implements `INotifyValueChanged<Vector2>`, so `value`, `RegisterValueChangedCallback` and bubbling `ChangeEvent<Vector2>` work like the built-in fields.
  - UXML attributes: `min-value`, `max-value`, `low-value`, `high-value`, `whole-numbers`.
- `Runtime/Styles/UIToolkitExtensionsControlStyles.uss` - `rangeSlider` styles (BEM classes exposed as constants), themeable via `--rangeSlider-*` custom properties.
- `Editor/UIToolkitExtensionsMenuOptions.cs` + `Editor/ControlTemplates/RangeSliderStarter.uxml` - `GameObject/UI Toolkit/Extensions/Range Slider` and `Assets/Create/UI Toolkit/Extensions/Range Slider Starter`.
- `CHANGELOG.md` (new Unreleased section), `README.md` (control count 25 -> 26), `Documentation~` control list.

### Behaviour changes compared with the uGUI version

- **Fixed:** `SetValueWithoutNotify(low, high)` clamped the new low against the *old* high. For example, going from 10..12 to (20, 80) gave 12..80.
- **Fixed:** a bar drag re-centred the range on the pointer (it jumped on the first move). It also moved low before high, so a fast drag could collapse the range. It now moves both ends by the drag distance and keeps the range size.
- **Fixed:** when both handles overlapped at the max, only the high handle could be grabbed, so the range was stuck. Now the first drag direction decides which handle moves.
- **New:** pressing the track outside the range jumps the nearest handle there and keeps dragging it. The original ignored these presses.
- **New:** keyboard / gamepad support. Tab to a handle, then left/right steps it (1 for whole numbers, otherwise 10% of the range, as the original `StepSize`). The uGUI version left `OnMove` unimplemented.
- **New:** if low/high sits on the min/max when that limit changes, it follows the new limit, so a full-range selection stays full. This also lets UXML set `min-value`/`max-value` then `low-value`/`high-value` without the values being clamped to the default 0..1 range first.

## Breaking Changes

- None. This only adds a new control.

## Related Submodule Changes

- None yet. A RangeSlider sample scene for `com.unity.uitoolkitextensions.examples` can follow in a separate PR.

## Testing status

* No tests have been added (the package has no test assembly yet).

### Manual testing status

- To do in the Unity Editor (6000.0): compile, add via `GameObject/UI Toolkit/Extensions/Range Slider`, check it in UI Builder and Play Mode:
  - drag each handle; drag the fill; press the track either side of the range; overlap both handles at min and at max, then drag each way;
  - toggle `whole-numbers`; change `min-value`/`max-value` in UI Builder; tab to the handles and use the arrow keys; disable the element with `SetEnabled(false)`.
@Dover8
Dover8 marked this pull request as ready for review November 17, 2026 14:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants