# Slider Primitive

Slider is a Starwind Runtime primitive in the form-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Slider anatomy with the Runtime wiring included.
```astro
---
import { Slider } from "@starwind-ui/astro/slider";
---

<Slider.Root>
  <Slider.Label>Volume</Slider.Label>
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>
```

### React
Use the React primitive adapter when Slider state participates in React rendering.
```tsx
import { Slider } from "@starwind-ui/react/slider";

export function Example() {
  return (
    <Slider.Root>
      <Slider.Label>Volume</Slider.Label>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  );
}
```

### HTML
Render the Slider data-sw-* contract yourself, then initialize createSlider.
```html
<div data-sw-slider role="group">
  <span data-sw-slider-label>Volume</span>
  <div data-sw-slider-control>
    <div data-sw-slider-track>
      <div data-sw-slider-indicator></div>
      <div data-sw-slider-thumb></div>
    </div>
  </div>
</div>

<script type="module">
  import { createSlider } from "@starwind-ui/runtime/slider";

  const root = document.querySelector("[data-sw-slider]");
  if (root) {
    createSlider(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render Slider anatomy.
```vue
<script setup lang="ts">
import Slider from "@starwind-ui/vue/slider";
</script>

<template>
  <Slider.Root>
    <Slider.Label>Volume</Slider.Label>
    <Slider.Control>
      <Slider.Track>
        <Slider.Indicator />
        <Slider.Thumb />
      </Slider.Track>
    </Slider.Control>
  </Slider.Root>
</template>
```
## API Reference
### Root
The main element that owns the Slider Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider` |
| Role | `group` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `SliderValue` | - | control | Controls the current Slider value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `SliderValue` | 0 | control | Sets the initial Slider value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| disabled | `boolean` | false | option | Disables the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| largeStep | `number` | 10 | option | Configures the large step option for the Root part. | - |
| max | `number` | 100 | option | Configures the max option for the Root part. | - |
| min | `number` | 0 | option | Configures the min option for the Root part. | - |
| minStepsBetweenValues | `number` | 0 | option | Configures the min steps between values option for the Root part. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| orientation | `SliderOrientation` | "horizontal" | option | Sets the Slider orientation. | - |
| step | `number` | 1 | option | Configures the step option for the Root part. | - |
| onValueChange | `(value: SliderValue, details: SliderValueChangeDetails) => void` | - | callback | Runs when the Slider value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| onValueCommitted | `(value: SliderValue, details: SliderValueCommitDetails) => void` | - | callback | Runs when on value committed changes for Slider. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-large-step` | prop | - | Reflects the large step prop on the Root part. |
| `data-max` | prop | - | Reflects the max prop on the Root part. |
| `data-min` | prop | - | Reflects the min prop on the Root part. |
| `data-min-steps-between-values` | prop | - | Reflects the min steps between values prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Root part. |
| `data-step` | prop | - | Reflects the step prop on the Root part. |
| `data-value` | state | - | Reflects the value state on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `SliderValue` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Slider value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `SliderValue` | SliderValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Slider. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| valueCommitted | onValueCommitted | starwind:value-committed | value: `SliderValue` | SliderValueCommitDetails | - | - | Fires when the user commits the value for Slider. | - |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Slider value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Slider is disabled from Runtime code. |
| `setName` | prop: name | - | No | Updates the Slider form field name from Runtime code. |
| `setOptions` | props: form, largeStep, max, min, minStepsBetweenValues, orientation, step | - | No | Updates Runtime options after initialization. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-slider`, `role`, `data-default-value`, `data-min`, `data-max`, `data-step`, `data-large-step`, `data-min-steps-between-values`, `data-orientation`, `data-value` | Range values and orientation styling must be present before controller hydration. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, value |
| Hidden input | input (range) |

### Control
Groups the interactive controls for Slider.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider-control` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-control` | runtime | - | Marks the Control part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| control | Yes |

### Track
The track that contains the Slider range.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider-track` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-track` | runtime | - | Marks the Track part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| track | Yes |

### Indicator
Visual state indicator rendered by Slider.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-indicator` | runtime | - | Marks the Indicator part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| indicator | Yes |

### Label
Text label associated with Slider.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-slider-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| label | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-slider-label` | Visible labels can be linked to slider thumbs by the runtime after hydration. |

### Thumb
The draggable thumb for Slider.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-slider-thumb` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| index | `number` | - | attribute | Sets the index attribute on the Thumb part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-thumb` | runtime | - | Marks the Thumb part so Starwind Runtime can find it. |
| `data-index` | prop | - | Reflects the index prop on the Thumb part. |
#### Refs
| Part | Public |
| --- | --- |
| thumb | Yes |

### Input
The native input synchronized by Slider.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-slider-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-slider-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-slider-input`, `type`, `aria-hidden`, `tabIndex` | Each thumb needs a nested range input placeholder so the runtime can wire form submission and input-change behavior. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | form, name, value |
| Hidden input | input (range) |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createSlider`](/docs/runtime/#create-slider) |
| Import | `@starwind-ui/runtime/slider` |
| Root part | root |
| Option props | defaultValue, disabled, form, largeStep, max, min, minStepsBetweenValues, name, orientation, step, value |
| Option lifecycles | disabled: setter-backed, form: setter-backed, largeStep: setter-backed, max: setter-backed, min: setter-backed, minStepsBetweenValues: setter-backed, name: setter-backed, orientation: setter-backed, step: setter-backed, value: setter-backed |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | form, name, value |
| Hidden input | input (range) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Slider](/docs/components/slider/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/slider` | `createSlider` |
| Astro Primitive | `@starwind-ui/astro/slider` | `Slider`, `SliderRoot`, `SliderControl`, `SliderTrack`, `SliderIndicator`, `SliderLabel`, `SliderThumb` |
| React Primitive | `@starwind-ui/react/slider` | `Slider`, `SliderRoot`, `SliderControl`, `SliderTrack`, `SliderIndicator`, `SliderLabel`, `SliderThumb` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Slider` |
| runtime-factory | `createSlider` |
| part | `Slider.Root` |
| part | `Slider.Control` |
| part | `Slider.Track` |
| part | `Slider.Indicator` |
| part | `Slider.Label` |
| part | `Slider.Thumb` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
### v0.1.0
- Introduced single and multi-value state, pointer dragging, keyboard interaction, and form participation.