For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt, and this page is available as Markdown at /next/ui/components/slider.md.
lynx-ui logo
lynx-ui
  • English
  • Slider

    A primitives-first slider component package for lynx-ui. It supports both single-value sliders and two-thumb range sliders.
    Info

    You can check the source code to understand how it works, and you're welcome to submit PRs to enhance its capabilities.

    Basic Usage

    Compose styled, disabled, and right-to-left sliders from the core primitives.

    Examples

    Controlled

    Control slider values externally, jump to presets, and snap to fixed steps.

    Dynamic Width

    Remeasure the track correctly when the slider container changes width.

    Facade

    Wrap the slider primitives in a reusable component with replaceable thumb content.

    Price Range

    Build a stepped two-thumb range with live values, committed values, and presets.

    Progress

    Omit the thumb to reuse the slider primitives as read-only progress indicators.

    Shapes

    Create distinct slider treatments by styling the track, indicator, and thumb.

    With ScrollView

    Preserve horizontal slider gestures inside nested horizontal and vertical scroll views.

    Structure

    A single-value slider uses one thumb.

    <SliderRoot>
      <SliderTrack>
        <SliderIndicator />
        <SliderThumb />
      </SliderTrack>
    </SliderRoot>

    A range slider uses two indexed thumbs.

    <SliderRoot value={range}>
      <SliderTrack>
        <SliderIndicator />
        <SliderThumb index={0} />
        <SliderThumb index={1} />
      </SliderTrack>
    </SliderRoot>

    Component API

    SliderRoot

    Root primitive props for a single-value or range slider. The generic selects the value shape and defaults to number for existing single-value usage. A range slider must provide its tuple through either value or defaultValue so the runtime can determine the shape. Range-thumb collision behavior is intentionally non-crossing: thumbs may meet, but the active thumb stops at the other value without swapping or pushing the other thumb.

    children
    TypeReactNode
    Primitive children composition, usually: SliderTrack containing SliderIndicator and optional SliderThumb.
    classNameiOSAndroidHarmony
    Typestring
    className
    defaultValue
    Typenumber | SliderRangeValue·Default0
    Initial value for uncontrolled usage. A single-value slider starts at 0 when omitted; a range slider must provide a tuple.
    disabled
    Typeboolean·Defaultfalse
    Disable the slider and prevent pointer/touch interaction.
    enableRTL
    Typeboolean·Defaultfalse
    Enable right-to-left layout. When true, the slider range grows from right to left.
    onDragging
    Type(value: number | SliderRangeValue) => void
    Triggered when dragging state changes, with the current slider value. The callback fires when dragging starts and when dragging ends.
    onValueChange
    Type(value: number | SliderRangeValue, source: SliderValueChangeSource) => void
    Triggered after slider-driven value updates, including dragging and SliderRef.updateValue. In controlled mode, use this callback to keep the external value prop in sync with the rendered value.
    onValueCommit
    Type(value: number | SliderRangeValue) => void
    Triggered at the end of a drag interaction with the final value.
    step
    Typenumber
    Stepping interval in range [0, 1]. When set, the value snaps to the nearest multiple of step.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    value
    Typenumber | SliderRangeValue
    Controlled slider value. Pass a number in [0, 1] or an ordered lower/upper tuple. Do not use together with defaultValue.

    State-based styling & rendering

    This component exposes runtime states through one or both of the following channels. The table lists only the channels available for each state:

    • UI variant class — when supported, a class like ui-<state> is toggled on the corresponding component node for selectors such as .ui-<state> { ... }.
    • Render-prop field — when supported and children is a function, the state is passed in via children({ <state>: boolean, ... }) for runtime-driven rendering.

    UI variants applied by SliderRoot.

    Class NameDescription
    ui-activeApplied from the start of a pointer or touch interaction until it ends.
    ui-disabledApplied when the slider is disabled.

    SliderTrack

    Track primitive props.

    SliderTrack establishes the measurement/layout coordinate space and renders the base rail.

    children
    TypeReactNode
    Usually includes SliderIndicator and optional SliderThumb.
    classNameiOSAndroidHarmony
    Typestring
    className
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    UI variants applied by SliderTrack.

    Class NameDescription
    ui-activeApplied from the start of a pointer or touch interaction until it ends.
    ui-disabledApplied when the slider is disabled.

    SliderIndicator

    Indicator primitive props.

    SliderIndicator is a pure visual layer. It fills from zero to the value in single-value mode and spans the selected interval in range mode.

    classNameiOSAndroidHarmony
    Typestring
    className
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    UI variants applied by SliderIndicator.

    Class NameDescription
    ui-activeApplied from the start of a pointer or touch interaction until it ends.
    ui-disabledApplied when the slider is disabled.

    SliderThumb

    Thumb primitive props.

    SliderThumb is positioned by the current ratio inside SliderTrack and does not own interaction logic.

    children
    TypeReactNode
    Custom thumb content.
    classNameiOSAndroidHarmony
    Typestring
    className
    indexiOSAndroidHarmony
    TypeSliderThumbIndex·Default0
    Value index represented by this thumb. A single-value slider uses the default index 0; a range slider uses 0 for the lower thumb and 1 for the upper thumb.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style

    UI variants applied by SliderThumb.

    Class NameDescription
    ui-activeApplied only to the thumb selected for the current pointer or touch interaction, from interaction start until it ends.
    ui-disabledApplied when the slider is disabled.

    SliderRef

    Imperative methods exposed by SliderRoot for the selected value shape. The generic defaults to number for compatibility with existing single-value refs; use SliderRef<SliderRangeValue> for a range slider.

    getValue
    Type() => number | SliderRangeValue
    Read the current slider value using the selected value shape.
    updateValue
    Type(value: number | SliderRangeValue, options?: SliderUpdateValueOptions) => void
    Imperatively set the slider value. Every number in the selected value shape uses the normalized range [0, 1].

    Supporting Types

    SliderRangeValue

    SliderRangeValue
    Typereadonly [number, number]
    Ordered lower and upper values for a range slider. Both values use the normalized [0, 1] scale. During dragging, the lower and upper thumbs may meet, but they never cross, swap identities, or push one another.

    SliderValue

    SliderValue
    Typenumber | SliderRangeValue
    Value accepted by SliderRoot: either one normalized value or an ordered lower/upper tuple.

    SliderThumbIndex

    SliderThumbIndex
    Type0 | 1
    Index of a slider thumb. A single-value slider uses index 0; a range slider uses index 0 for the lower value and 1 for the upper value.

    SliderValueChangeSource

    SliderValueChangeSource
    Typeexternal | drag
    Source of a value change. - external: value updated by imperative API calls. - drag: value updated by pointer/touch dragging.

    SliderUpdateValueOptions

    Options used by SliderRef.updateValue.

    force
    Typeboolean·Defaultfalse
    Bypass drag-time guard and force update even while dragging.
    source
    TypeSliderValueChangeSource·Default'external'
    Mark the update source for analytics/logic branching.
    Except as otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License, and code samples are licensed under the Apache License 2.0.