Skip to content
Kimenpre-v1documentation home
Color scheme

ki-slider

Use ki-slider for approximate values such as volume, exposure or a price filter. Use a number input for exact entry and a radio group for a few named choices.

Theme for this example
Color scheme for this example
<ki-slider label="Volume" name="volume" value="60" marks="5" format="percent"></ki-slider>
<ki-slider label="Price per night" name="price" range value="20,80" format="currency" currency="EUR"></ki-slider>

Use centered to fill from the midpoint and show a center tick on a single-thumb scale. Set orientation="vertical" to increase from bottom to top. Horizontal scales follow the enclosing writing direction.

Theme for this example
Color scheme for this example
<ki-slider label="Exposure" centered min="-50" max="50" value="-20"></ki-slider>
<ki-slider label="Bass" orientation="vertical" max="10" value="4"></ki-slider>

Keyboard and forms

Tab reaches each thumb in order. The arrows move one step, Page Up and Page Down move ten, and Home and End reach the focused thumb’s current limits. Horizontal arrows follow the scale’s direction. Up always increases.

Provide a specific label and use help-text for extra context. Use minimum-label and maximum-label to localize the range thumb suffixes. format changes the readout and the accessible value. A value of 60 displays as 60% in percent format.

Each named slider submits one form entry. The range above submits 20,80. Reset restores the initial selection. Listen for input to preview changes and change to act after a pointer release or keyboard adjustment.

API reference

When to use: coarse adjustments such as volume, balance or a price filter, with a descriptive label.

When not to use: when people need to enter exact numbers or choose among a few named options. Use a number input or radio group for those tasks.

Properties & attributes

AttributePropertyTypeDefaultDescription
centeredcenteredbooleanfalseShows a midpoint tick and fills from that point to a single thumb.
currencycurrencystring'EUR'ISO 4217 code used with currency format.
disableddisabledbooleanfalseMakes the slider unavailable for pointer, keyboard and form submission.
formatformat"currency" | "number" | "percent"'number'Display format for the readout and accessible values.
help-texthelpTextstring | undefined–Optional supporting text, read as the description of each thumb.
labellabelstring | undefined'Slider'Visible base name. Use a task-specific, localized label.
marksmarksnumber0Number of evenly spaced tick intervals, up to 100. Zero hides ticks.
maxmaxnumber100Inclusive upper bound. A maximum below min collapses the scale.
maximum-labelmaximumLabelstring | undefined'maximum'Localized suffix for the upper thumb's accessible name.
minminnumber0Inclusive lower bound and step origin.
minimum-labelminimumLabelstring | undefined'minimum'Localized suffix for the lower thumb's accessible name.
namenamestring | undefined–Native form key. Omit when the value should remain local to the control.
orientationorientation"horizontal" | "vertical"'horizontal'Axis of the scale. A vertical scale increases towards the top.
rangerangebooleanfalseEnables two non-crossing thumbs in minimum then maximum tab order.
stepstepnumber1Positive increment. Values snap from min and max is always reachable.
valuevaluenumber | string | undefined–Current selection as a number or, in range mode, a comma-separated pair. HTML attributes also accept the scalar as numeric text. Defaults to min for one thumb and to both bounds for a range. User updates are normalized.

Events

EventDetail typeDescription
changeEventBubbles once when a pointer operation commits a different selection or a keyboard action changes it. Read the current host value. For updates during a drag, listen for the standard bubbling input event. Programmatic updates and form resets are silent.

CSS parts

PartDescription
center-tickMidpoint mark on a centered scale.
fieldLayout containing the visible label, value, controls and help.
fillActive portion of the rail.
helpSupporting text associated with each thumb.
labelVisible text used to name the control.
markDecorative scale mark at an interval boundary.
thumbFocusable pointer target for one end of the selection.
trackInactive rail between the two ends of the scale.
valueFormatted value or interval shown beside the label.

CSS custom properties

The public styling contract of ki-slider: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-slider-coarse-targetMinimum target size on a coarse pointer.
--ki-slider-fill-backdrop-filterOptional effect behind the active rail.
--ki-slider-fill-bgColour of the active section of the rail.
--ki-slider-fill-bg-imageOptional image painted on the active rail.
--ki-slider-gapGap between the slider control and its labels.
--ki-slider-label-bgBackground beneath the field label.
--ki-slider-label-fgInk of the field label.
--ki-slider-mark-widthThickness of each interval tick.
--ki-slider-radiusRound rail, grip and midpoint tick corners.
--ki-slider-text-bgBackground beneath the value readout and help.
--ki-slider-text-fgInk of the value readout and help.
--ki-slider-thumb-backdrop-filterOptional effect behind the grip.
--ki-slider-thumb-bgGrip surface behind the outline.
--ki-slider-thumb-bg-imageOptional image painted on the grip.
--ki-slider-thumb-borderOutline colour of the visible grip.
--ki-slider-thumb-border-widthOutline thickness of the visible grip.
--ki-slider-thumb-shadowOptional grip elevation.
--ki-slider-thumb-sizeDiameter of the visible grip within the pointer target.
--ki-slider-track-backdrop-filterOptional effect behind the inactive rail.
--ki-slider-track-bgInactive rail colour against the surrounding surface.
--ki-slider-track-bg-imageOptional image painted on the inactive rail.
--ki-slider-track-heightInactive rail thickness.
--ki-slider-vertical-lengthLength of the vertical rail.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.

Workshop

Open ki-slider in Storybook