Checkbox

Checkbox allows users to select or mark a single item as selected.

To use multiple checkboxes together, use the checkbox_group component.

Example

from deephaven import ui

cb = ui.checkbox("Unsubscribe")

UI recommendations

Recommendations for creating checkboxes:

1. Use emphasized checkboxes for forms, settings, or to highlight selected items like cards or table rows. Use non-emphasized checkboxes in application panels with monochrome components to keep the focus on the main content.
2. Use standalone checkboxes when the context is clear without a text label, such as when a checkbox is associated with other controls within a panel.
3. Checkboxes and radio buttons should not be used interchangably. Use checkboxes to allow multiple selections (or none) from a list. Use radio buttons to select only one option from a list of mutually exclusive choices.
4. Checkboxes should be used when selecting (ie., multiple table rows), whereas switches should be used for activation (ie., on/off states).

Consider using a checkbox for individual selections or when marking a single item as selected. For a set of related checkboxes, use a checkbox_group to manage multiple selections within a group. If you need to display a list of checkboxes driven by a Deephaven table, use a list_view to dynamically generate the checkboxes.

Content

Checkbox’s accept a child, which is rendered as the label of the checkbox.

from deephaven import ui

my_checkbox_basic = ui.checkbox("Basic Checkbox")

Value

Checkboxes are not selected by default. Use the default_selected prop to set the initial state (uncontrolled) or the is_selected prop to control the selected state.

from deephaven import ui


@ui.component
def ui_checkbox_content_examples():
    selected, set_selected = ui.use_state(False)
    return ui.flex(
        ui.checkbox("Subscribe (uncontrolled)", default_selected=True),
        ui.checkbox(
            "Subscribe (uncontrolled)", is_selected=selected, on_change=set_selected
        ),
        direction="column",
    )


my_checkbox_content_examples = ui_checkbox_content_examples()

Indeterminate state

A checkbox can be set to an indeterminate state using the is_indeterminate prop, which overrides its appearance. The Checkbox remains visually indeterminate until the prop is set to false, regardless of user interaction.

from deephaven import ui


my_checkbox_is_indeterminate_example = ui.checkbox(
    "Indeterminate State", is_indeterminate=True
)

HTML Forms

Checkbox’s 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_checkbox_name_example = ui.form(ui.checkbox("Sample Label", name="Sample Name"))

Events

Checkboxes accept an on_change prop, which is triggered whenever the Checkbox is clicked

from deephaven import ui


@ui.component
def ui_checkbox_event_example():
    selected, set_selected = ui.use_state(False)
    return ui.flex(
        ui.checkbox("Subscribe", is_selected=selected, on_change=set_selected),
        ui.text(value="Subscribed!" if selected else "Not subscribed!"),
        direction="column",
    )


my_checkbox_event_example = ui_checkbox_event_example()

Validation

Checkboxes can indicate a validation state to show if the current value is invalid, via the is_invalid prop. Since the invalid state is only shown through a color change, ensure the validation error is also communicated in another accessible way.

from deephaven import ui


@ui.component
def ui_checkbox_validation_example():
    invalid, set_invalid = ui.use_state(False)
    return [
        ui.button(
            "Make checkbox valid" if invalid else "Make checkbox invalid",
            on_press=lambda: set_invalid(not invalid),
        ),
        ui.checkbox("I accept the terms and conditions", is_invalid=invalid),
    ]


my_checkbox_validation_example = ui_checkbox_validation_example()

API reference

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

Returns: Element The rendered checkbox.