Slider
Choose scalar or range values on horizontal or vertical tracks.
Choose scalar or range values on horizontal or vertical tracks.
Contract
| Axis | Contract |
|---|---|
| Value | TRSlider carries a single double. Ranges are a separate widget, TRRangeSlider, which carries a RangeValues. Each widget has an uncontrolled constructor taking defaultValue and a .controlled constructor taking value. |
| Range | min, max, and step bound and snap every pointer and keyboard change. On TRRangeSlider, minGap is a distance in value units, not a step count, and the thumb being driven absorbs it. Thumbs stop at each other instead of pushing or swapping. |
| Form | There is no name and no hidden input. Put TRSliderFormField or TRRangeSliderFormField inside a Flutter Form and read the value through validator, onSaved, and FormState. |
| Validation | Validation rules live on the form field. It passes its message down as errorText, which prints below the track and tints the filled part of it. Set autovalidateMode to decide whether the message appears before the first submit. Outside a Form, pass errorText yourself. |
| Keyboard | A focused track moves by one step on Right and Up, and back on Left and Down. There is no large step, and Page Up, Page Down, Home, and End are not handled. On TRRangeSlider the arrow keys drive the thumb the last pointer press selected, which starts as the lower one. |
| Labeling | label draws a heading row above the track with the current value beside it, and labelBuilder formats that value for both the visible text and the semantics. Set semanticLabel when the accessible name should differ from the visible one, or when there is no visible label. |
Reach for TRSlider when the reader picks an approximate value along a known scale, such as a volume or a traffic share. Use TRTextField or TRNumberField when the exact number matters more than the position.
Install
Add the package, then import its public library.
flutter pub add tinyrack_uiimport 'package:tinyrack_ui/tinyrack_ui.dart';Playground
Usage
import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';
TRSlider.controlled(
label: 'Traffic',
value: traffic,
onValueChange: (value) => setState(() => traffic = value),
)Examples
Volume permalink
The uncontrolled constructor owns the value. Give the slider a bounded width, since it fills the space its parent offers.
Sizes permalink
`uiSize` scales the thumb and the space around the track while the track thickness stays the same. Use `TRUiSize.md` when the slider sits in a dense control surface.
Orientations permalink
A vertical slider puts the maximum at the top, takes a fixed width, and fills the height it is given. Constrain that height so the track has room.
Disabled slider permalink
Set `enabled: false` when the value should stay readable but cannot be changed. The increase and decrease actions leave the semantics node, so assistive technology no longer offers them.
Two-thumb range permalink
`TRRangeSlider` carries a `RangeValues` and keeps the thumbs `minGap` apart in value units. `labelBuilder` formats each end for both the heading row and the semantics value, and the arrow keys drive whichever thumb the last pointer press selected.
Form submission permalink
`TRSliderFormField` joins the surrounding `Form`, so `FormState.save` collects the value through `onSaved`. There is no `name` and no hidden input to serialize.
Field-owned validation permalink
Move the thumb below 60% to reveal the error, then raise it to clear the message. `AutovalidateMode.onUserInteraction` keeps the field quiet until the reader touches it, and `validate` guards `save` on submit.
API
TRSlider properties
| Prop | Type / default | Purpose |
|---|---|---|
defaultValue | double · 0 | Sets the starting value of the uncontrolled constructor. The widget then owns the value and reports each change through onValueChange. |
value | double? · required on .controlled | Drives the thumb from your own state. The widget never moves on its own, so update the state inside onValueChange. |
onValueChange | ValueChanged<double>? · null | Fires on every pointer and keyboard change while the interaction is still in progress. There is no separate commit callback, so debounce the work yourself when a drag would be expensive. |
min, max, step | double · 0, 100, 1 | Define the scale. Values are clamped to the bounds and snapped to the nearest step. The constructors assert min < max and step > 0. |
label | String? · null | Adds a heading row above the track showing the label and the current value. Leave it null for a bare track, and give the control a semanticLabel instead. |
labelBuilder | TRSliderLabelBuilder? · null | Formats the value for the heading row and the semantics value. Use it for units and percentages; whole numbers otherwise print without a decimal part. |
semanticLabel | String? · null | Names the control for assistive technology. It falls back to label, so set it when the visible label is missing or too terse to stand alone. |
errorText | String? · null | Prints a danger-toned message below the track and tints the filled part of it. TRSliderFormField supplies this from its validator, so set it directly only outside a Form. |
uiSize | TRUiSize · TRUiSize.md | Scales the thumb and the space reserved around the track. The track thickness stays the same at every size. Use TRUiSize.md on dense surfaces. |
vertical | bool · false | Turns the track upright, with the maximum at the top. A vertical slider takes a fixed width and fills the height its parent gives it, so constrain that height. |
enabled | bool · true | Blocks pointer and keyboard changes and drops the increase and decrease actions from the semantics node. The value stays visible. Flutter uses enabled, not the disabled prop the React page documents. |
TRRangeSlider properties
| Prop | Type / default | Purpose |
|---|---|---|
defaultValue | RangeValues · RangeValues(25, 75) | Sets the starting pair for the uncontrolled constructor. The .controlled constructor takes value instead and requires it. |
minGap | double · 0 | Keeps the thumbs at least this far apart in value units. The thumb being driven stops at the gap; the other one stays where the reader put it. |
onValueChange | ValueChanged<RangeValues>? · null | Reports the whole pair on every change, after clamping and the minimum gap are applied. |
labelBuilder | TRSliderLabelBuilder? · null | Formats each end separately. The heading row then joins the two results with an en dash, as in 20%–80%. |
TRSliderFormField and TRRangeSliderFormField
| Prop | Type / default | Purpose |
|---|---|---|
initialValue | double · 0 / RangeValues · RangeValues(25, 75) | Seeds the field. FormState.reset returns the slider to this value. |
validator | FormFieldValidator? · null | Returns an error message to block FormState.validate, or null to accept the value. The field forwards the message to the slider as errorText. |
autovalidateMode | AutovalidateMode? · null | Decides when the validator runs. AutovalidateMode.onUserInteraction keeps the field quiet until the reader moves the thumb, then clears the error as soon as the value becomes acceptable. |
onSaved | FormFieldSetter? · null | Receives the value when FormState.save runs. Use it to collect the submitted result after a successful validate. |