@base-ui-components/react
Version:
Base UI is a library of headless ('unstyled') React components and low-level hooks. You gain complete control over your app's CSS and accessibility features.
178 lines • 6.71 kB
TypeScript
import * as React from 'react';
import type { BaseUIComponentProps, Orientation } from "../../utils/types.js";
import { type BaseUIChangeEventDetails, type BaseUIGenericEventDetails } from "../../utils/createBaseUIEventDetails.js";
import type { FieldRoot } from "../../field/root/FieldRoot.js";
import { REASONS } from "../../utils/reasons.js";
/**
* Groups all parts of the slider.
* Renders a `<div>` element.
*
* Documentation: [Base UI Slider](https://base-ui.com/react/components/slider)
*/
export declare const SliderRoot: {
<Value extends number | readonly number[]>(props: SliderRoot.Props<Value> & {
ref?: React.Ref<HTMLDivElement>;
}): React.JSX.Element;
};
export interface SliderRootState extends FieldRoot.State {
/**
* The index of the active thumb.
*/
activeThumbIndex: number;
/**
* Whether the component should ignore user interaction.
*/
disabled: boolean;
/**
* Whether the thumb is currently being dragged.
*/
dragging: boolean;
max: number;
min: number;
/**
* The minimum steps between values in a range slider.
* @default 0
*/
minStepsBetweenValues: number;
/**
* The component orientation.
*/
orientation: Orientation;
/**
* The step increment of the slider when incrementing or decrementing. It will snap
* to multiples of this value. Decimal values are supported.
* @default 1
*/
step: number;
/**
* The raw number value of the slider.
*/
values: readonly number[];
}
export interface SliderRootProps<Value extends number | readonly number[] = number | readonly number[]> extends BaseUIComponentProps<'div', SliderRoot.State> {
/**
* The uncontrolled value of the slider when it’s initially rendered.
*
* To render a controlled slider, use the `value` prop instead.
*/
defaultValue?: Value;
/**
* Whether the slider should ignore user interaction.
* @default false
*/
disabled?: boolean;
/**
* Options to format the input value.
*/
format?: Intl.NumberFormatOptions;
/**
* The locale used by `Intl.NumberFormat` when formatting the value.
* Defaults to the user's runtime locale.
*/
locale?: Intl.LocalesArgument;
/**
* The maximum allowed value of the slider.
* Should not be equal to min.
* @default 100
*/
max?: number;
/**
* The minimum allowed value of the slider.
* Should not be equal to max.
* @default 0
*/
min?: number;
/**
* The minimum steps between values in a range slider.
* @default 0
*/
minStepsBetweenValues?: number;
/**
* Identifies the field when a form is submitted.
*/
name?: string;
/**
* The component orientation.
* @default 'horizontal'
*/
orientation?: Orientation;
/**
* The granularity with which the slider can step through values. (A "discrete" slider.)
* The `min` prop serves as the origin for the valid values.
* We recommend (max - min) to be evenly divisible by the step.
* @default 1
*/
step?: number;
/**
* The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down.
* @default 10
*/
largeStep?: number;
/**
* How the thumb(s) are aligned relative to `Slider.Control` when the value is at `min` or `max`:
* - `center`: The center of the thumb is aligned with the control edge
* - `edge`: The thumb is inset within the control such that its edge is aligned with the control edge
* - `edge-client-only`: Same as `edge` but renders after React hydration on the client, reducing bundle size in return
* @default 'center'
*/
thumbAlignment?: 'center' | 'edge' | 'edge-client-only';
/**
* Controls how thumbs behave when they collide during pointer interactions.
*
* - `'push'` (default): Thumbs push each other without restoring their previous positions when dragged back.
* - `'swap'`: Thumbs swap places when dragged past each other.
* - `'none'`: Thumbs cannot move past each other; excess movement is ignored.
*
* @default 'push'
*/
thumbCollisionBehavior?: 'push' | 'swap' | 'none';
/**
* The value of the slider.
* For ranged sliders, provide an array with two values.
*/
value?: Value;
/**
* Callback function that is fired when the slider's value changed.
* You can pull out the new value by accessing `event.target.value` (any).
*
* The `eventDetails.reason` indicates what triggered the change:
*
* - `'input-change'` when the hidden range input emits a change event (for example, via form integration)
* - `'track-press'` when the control track is pressed
* - `'drag'` while dragging a thumb
* - `'keyboard'` for keyboard input
* - `'none'` when the change is triggered without a specific interaction
*/
onValueChange?: (value: Value extends number ? number : Value, eventDetails: SliderRoot.ChangeEventDetails) => void;
/**
* Callback function that is fired when the `pointerup` is triggered.
* **Warning**: This is a generic event not a change event.
*
* The `eventDetails.reason` indicates what triggered the commit:
*
* - `'drag'` while dragging a thumb
* - `'track-press'` when the control track is pressed
* - `'keyboard'` for keyboard input
* - `'input-change'` when the hidden range input emits a change event (for example, via form integration)
* - `'none'` when the commit occurs without a specific interaction
*/
onValueCommitted?: (value: Value extends number ? number : Value, eventDetails: SliderRoot.CommitEventDetails) => void;
}
export interface SliderRootChangeEventCustomProperties {
/**
* The index of the active thumb at the time of the change.
*/
activeThumbIndex: number;
}
export type SliderRootChangeEventReason = typeof REASONS.inputChange | typeof REASONS.trackPress | typeof REASONS.drag | typeof REASONS.keyboard | typeof REASONS.none;
export type SliderRootChangeEventDetails = BaseUIChangeEventDetails<SliderRoot.ChangeEventReason, SliderRootChangeEventCustomProperties>;
export type SliderRootCommitEventReason = typeof REASONS.inputChange | typeof REASONS.trackPress | typeof REASONS.drag | typeof REASONS.keyboard | typeof REASONS.none;
export type SliderRootCommitEventDetails = BaseUIGenericEventDetails<SliderRoot.CommitEventReason>;
export declare namespace SliderRoot {
type State = SliderRootState;
type Props<Value extends number | readonly number[] = number | readonly number[]> = SliderRootProps<Value>;
type ChangeEventReason = SliderRootChangeEventReason;
type ChangeEventDetails = SliderRootChangeEventDetails;
type CommitEventReason = SliderRootCommitEventReason;
type CommitEventDetails = SliderRootCommitEventDetails;
}