Range Slider

Range sliders allow users to quickly select a subset range within a fixed range and should be used when the upper and lower bounds of the range are constant.

Example

from deephaven import ui

my_range_slider_basic = ui.range_slider(
    default_value={"start": 18, "end": 80}, label="Age range"
)

Range Slider Basic Example

UI recommendations

Recommendations for creating range sliders:

  1. Every range slider should have a label specified. Without one, the range 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 slider instead of a range_slider when users should select a singular value or a number_field when the range is large and sliding between the upper and lower bound is no longer quick.

Value

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

from deephaven import ui


@ui.component
def range_slider_value_example():
    value, set_value = ui.use_state({"start": 25, "end": 75})

    def handle_value_change(new_value):
        print(f"Range changed to {new_value}")
        set_value(new_value)

    return [
        ui.range_slider(
            default_value={"start": 25, "end": 75}, label="Range (uncontrolled)"
        ),
        ui.range_slider(
            value=value, on_change=handle_value_change, label="Range (controlled)"
        ),
    ]


my_range_slider_value_example = range_slider_value_example()

Scale

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

The step prop changes the increments in which the range slider changes.

from deephaven import ui


@ui.component
def range_slider_range_step_examples():
    return [
        ui.range_slider(
            default_value={"start": 75, "end": 100},
            min_value=50,
            max_value=150,
            label="Range",
        ),
        ui.range_slider(
            default_value={"start": 10, "end": 100},
            min_value=0,
            max_value=500,
            step=10,
            label="Range",
        ),
    ]


my_range_slider_range_step_examples = range_slider_range_step_examples()

HTML Forms

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

from deephaven import ui


my_range_slider_name_example = ui.form(
    ui.range_slider(
        label="Opacity", default_value={"start": 50, "end": 100}, name="Opacity Range"
    )
)

Labeling

Value labels are shown above the range 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.

from deephaven import ui


my_range_slider_label_example = ui.flex(
    ui.range_slider(label="Jeans price range", default_value={"start": 75, "end": 100}),
    ui.range_slider(
        label="Shoes price range",
        label_position="side",
        default_value={"start": 50, "end": 100},
    ),
    ui.range_slider(
        label="Cakes to buy",
        show_value_label=False,
        default_value={"start": 15, "end": 30},
    ),
    direction="column",
    gap="size-500",
)

Contextual Help

A ui.contextual_help can be passed into the contextual_help prop to provide additional information about the range slider.

from deephaven import ui


my_range_slider_contextual_help_example = ui.range_slider(
    label="Search Radius",
    min_value=0,
    max_value=100,
    default_value={"start": 15, "end": 60},
    contextual_help=ui.contextual_help(
        ui.heading("Ranking"),
        ui.content("Search results are sorted by distance from city center."),
    ),
)

Disabled

Setting the is_disabled prop disables the range slider.

from deephaven import ui


my_range_slider_disabled_example = ui.range_slider(
    label="Price filter", default_value={"start": 25, "end": 50}, 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 range slider component.

ParametersTypeDefaultDescription
start_namestr |
None
NoneThe name of the start input element.
end_namestr |
None
NoneThe name of the end input element.
label_positionLiteral['top', 'side']'top'The position of the label relative to the slider.
show_value_labelbool |
None
NoneWhether the value label should be displayed. True by default if the label is provided.
contextual_helpAny |
None
NoneA ContextualHelp element to place next to the label.
orientationLiteral['horizontal', 'vertical']'horizontal'The orientation of the slider.
is_disabledbool |
None
NoneWhether the slider is disabled.
min_valuefloat0The minimum value of the slider.
max_valuefloat100The maximum value of the slider.
stepfloat1The step value for the slider.
valueSliderChange |
None
NoneThe current value of the slider.
default_valueSliderChange |
None
NoneThe default value of the slider.
labelAny |
None
NoneThe content to display as the label.
namestr |
None
NoneThe name of the input element, used when submitting an HTML form.
keystr |
None
NoneA unique identifier used by React to render elements in a list.