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"
)
UI recommendations
Recommendations for creating range sliders:
- 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_labelprop. - 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.
| Parameters | Type | Default | Description |
|---|---|---|---|
| start_name | str | None | None | The name of the start input element. |
| end_name | str | None | None | The name of the end input element. |
| label_position | Literal['top', 'side'] | 'top' | The position of the label relative to the slider. |
| show_value_label | bool | None | None | Whether the value label should be displayed. True by default if the label is provided. |
| contextual_help | Any | None | None | A ContextualHelp element to place next to the label. |
| orientation | Literal['horizontal', 'vertical'] | 'horizontal' | The orientation of the slider. |
| is_disabled | bool | None | None | Whether the slider is disabled. |
| min_value | float | 0 | The minimum value of the slider. |
| max_value | float | 100 | The maximum value of the slider. |
| step | float | 1 | The step value for the slider. |
| value | SliderChange | None | None | The current value of the slider. |
| default_value | SliderChange | None | None | The default value of the slider. |
| label | Any | None | None | The content to display as the label. |
| name | str | None | None | The name of the input element, used when submitting an HTML form. |
| key | str | None | None | A unique identifier used by React to render elements in a list. |