# Slider

Sliders allow users to quickly select a value within a fixed range and should be used when the range’s upper and lower bounds are constant.

## Example

```python
from deephaven import ui


my_slider_basic = ui.slider(default_value=12, label="Cookies to buy")
```

## UI recommendations

Recommendations for creating sliders:

1. Every slider should have a [label]() specified. Without one, the slider is ambiguous. In the rare case that context is sufficient, the label is unnecessary; you must still include an aria-label via the `aria_label` prop.
2. The label and contextual help text should be in sentence case.

Consider using a [`range_slider`](range_slider.md) when users should select a subset range or a `number_field` when the range is large or greater precision is required.

## Value

Sliders are controlled with the `value` prop and uncontrolled with the `default_value` prop. This value must fall between the slider’s minimum and maximum values, which by default are 0 and 100, respectively.

```python
from deephaven import ui


@ui.component
def slider_value_example():
    value, set_value = ui.use_state(25)
    return [
        ui.slider(default_value=25, label="Cookies to buy (Uncontrolled)"),
        ui.slider(
            value=value, on_change=set_value, label="Cookies to buy (Controlled)"
        ),
    ]


my_slider_value_example = slider_value_example()
```

## Scale

Setting the `min_value` and `max_value` props configures a custom scale for the slider.

The `step` prop changes the increments that the slider changes.

```python
from deephaven import ui


@ui.component
def slider_range_step_examples():
    return [
        ui.slider(
            default_value=100, min_value=50, max_value=150, label="Cookies to buy"
        ),
        ui.slider(
            default_value=100,
            min_value=0,
            max_value=1000,
            step=100,
            label="Donuts to buy for group event",
        ),
    ]


my_slider_range_step_examples = slider_range_step_examples()
```

## HTML Forms

Sliders can support a `name` prop for integration with HTML forms, allowing for easy identification of a value on form submission.

```python
from deephaven import ui


my_slider_name_example = ui.form(
    ui.slider(label="Opacity", default_value=50, name="opacity")
)
```

## Labeling

Value labels are shown above the slider by default but can be moved to the side or hidden using the `label_position` prop.

Note that if the `label` prop is set, the `show_value_label` is set to True by default.

```python
from deephaven import ui


my_slider_label_example = ui.flex(
    ui.slider(label="Cookies to buy", default_value=25),
    ui.slider(label="Donuts to buy", label_position="side", default_value=25),
    ui.slider(label="Cakes to buy", show_value_label=False, default_value=25),
    direction="column",
    gap="size-500",
)
```

## Fill

The `is_filled` prop can be set to fill the slider. The `fill_offset` prop can be set to apply an offset for the fill.

```python
from deephaven import ui


my_slider_fill_example = ui.flex(
    ui.slider(
        label="Contrast",
        min_value=-5,
        max_value=5,
        default_value=0.75,
        step=0.05,
        is_filled=True,
    ),
    ui.slider(
        label="Exposure",
        min_value=-5,
        max_value=5,
        default_value=1.83,
        step=0.01,
        fill_offset=1,
        is_filled=True,
    ),
    direction="column",
    gap="size-300",
)
```

## Gradient

The `track_gradient` prop applies a gradient to the slider’s fill.

```python
from deephaven import ui


my_slider_gradient_example = ui.slider(
    label="Filter density",
    track_gradient=["white", "rgba(177,141,32,1)"],
    default_value=0.3,
    max_value=1,
    step=0.01,
    is_filled=True,
)
```

## Contextual Help

To provide additional information about the slider, a `UI.contextual_help` can be passed into the `contextual_help` prop.

```python
from deephaven import ui


my_slider_contextual_help_example = ui.slider(
    label="Exposure",
    min_value=-100,
    max_value=100,
    default_value=0,
    is_filled=True,
    fill_offset=0,
    contextual_help=ui.contextual_help(
        ui.heading("What is exposure?"),
        ui.content("Exposure adjusts how bright the image is"),
    ),
)
```

## Disabled

Setting the `is_disabled` prop disables the slider.

```python
from deephaven import ui


my_slider_disabled_example = ui.slider(
    label="Cookies to share", default_value=0, is_disabled=True
)
```

## API Reference

Sliders allow users to quickly select a value within a range. They should be used when the upper and lower bounds to the range are invariable.

**Returns:** `Element` The rendered slider component.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "slider", "parameters": [{"name": "is_filled", "type": "bool | None", "description": "Whether the slider should be filled between the start of the slider and the current value.", "default": "None"}, {"name": "fill_offset", "type": "float | None", "description": "The offset of the filled area from the start of the slider.", "default": "None"}, {"name": "track_gradient", "type": "list[str] | None", "description": "The background of the track, specified as the stops for a CSS background: linear-gradient(to right/left, ...trackGradient).", "default": "None"}, {"name": "label_position", "type": "Literal['top', 'side']", "description": "The position of the label relative to the slider.", "default": "'top'"}, {"name": "show_value_label", "type": "bool | None", "description": "Whether the value label should be displayed. True by default if the label is provided.", "default": "None"}, {"name": "contextual_help", "type": "Any | None", "description": "A ContextualHelp element to place next to the label.", "default": "None"}, {"name": "orientation", "type": "Literal['horizontal', 'vertical']", "description": "The orientation of the slider.", "default": "'horizontal'"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the slider is disabled.", "default": "None"}, {"name": "min_value", "type": "float", "description": "The minimum value of the slider.", "default": "0"}, {"name": "max_value", "type": "float", "description": "The maximum value of the slider.", "default": "100"}, {"name": "step", "type": "float", "description": "The step value for the slider.", "default": "1"}, {"name": "value", "type": "float | None", "description": "The current value of the slider.", "default": "None"}, {"name": "default_value", "type": "float | None", "description": "The default value of the slider.", "default": "None"}, {"name": "label", "type": "Any | None", "description": "The content to display as the label.", "default": "None"}, {"name": "name", "type": "str | None", "description": "The name of the input element, used when submitting an HTML form.", "default": "None"}, {"name": "on_change_end", "type": "Callable[[float], None] | None", "description": "Function called when the slider stops moving", "default": "None"}, {"name": "on_change", "type": "Callable[[float], None] | None", "description": "Function called when the input value changes", "default": "None"}, {"name": "flex", "type": "str | float | bool | None", "description": "When used in a flex layout, specifies how the element will grow or shrink to fit the space available.", "default": "None"}, {"name": "flex_grow", "type": "float | None", "description": "When used in a flex layout, specifies how the element will grow to fit the space available.", "default": "None"}, {"name": "flex_shrink", "type": "float | None", "description": "When used in a flex layout, specifies how the element will shrink to fit the space available.", "default": "None"}, {"name": "flex_basis", "type": "str | float | None", "description": "When used in a flex layout, specifies the initial main size of the element.", "default": "None"}, {"name": "align_self", "type": "Literal['auto', 'normal', 'start', 'end', 'center', 'flex-start', 'flex-end', 'self-start', 'self-end', 'stretch'] | None", "description": "Overrides the alignItems property of a flex or grid container.", "default": "None"}, {"name": "justify_self", "type": "Literal['auto', 'normal', 'start', 'end', 'flex-start', 'flex-end', 'self-start', 'self-end', 'center', 'left', 'right', 'stretch'] | None", "description": "Species how the element is justified inside a flex or grid container.", "default": "None"}, {"name": "order", "type": "int | None", "description": "The layout order for the element within a flex or grid container.", "default": "None"}, {"name": "grid_area", "type": "str | None", "description": "When used in a grid layout specifies, specifies the named grid area that the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "When used in a grid layout, specifies the row the element should be placed in within the grid.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "When used in a grid layout, specifies the column the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting row to span within the grid.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending row to span within the grid.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting column to span within the grid.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending column to span within the grid.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin for all four sides of the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin for the top side of the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin for the bottom side of the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin for the logical start side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin for the logical end side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin for the left and right sides of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin for the top and bottom sides of the element.", "default": "None"}, {"name": "width", "type": "str | float | None", "description": "The width of the element.", "default": "None"}, {"name": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width of the element.", "default": "None"}, {"name": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height of the element.", "default": "None"}, {"name": "max_height", "type": "str | float | None", "description": "The maximum height of the element.", "default": "None"}, {"name": "position", "type": "Literal['static', 'relative', 'absolute', 'fixed', 'sticky'] | None", "description": "The position of the element.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The distance from the top of the containing element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The distance from the bottom of the containing element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The distance from the left of the containing element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The distance from the right of the containing element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The distance from the start of the containing element, depending on layout direction.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element, depending on layout direction.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stack order of the element.", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Whether the element is hidden.", "default": "None"}, {"name": "id", "type": "str | None", "description": "The unique identifier of the element.", "default": "None"}, {"name": "aria_label", "type": "str | None", "description": "The label for the element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "The id of the element that labels the current element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "The id of the element that describes the current element.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "The id of the element that provides additional information about the current element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "A CSS class to apply to the element.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "A CSS style to apply to the element.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />