diff --git a/plugins/ui/docs/components/checkbox.md b/plugins/ui/docs/components/checkbox.md new file mode 100644 index 000000000..dae59265f --- /dev/null +++ b/plugins/ui/docs/components/checkbox.md @@ -0,0 +1,133 @@ +# Checkbox + +Checkbox allows users to select or mark a single item as selected. + +To use multiple checkboxes together, use the `checkbox_group` component. + +## Example + +```python +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`](./checkbox.md) for individual selections or when marking a single item as selected. For a set of related checkboxes, use a [`checkbox_group`](./checkbox_group.md) 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`](./list_view.md) to dynamically generate the checkboxes. + +## Content + +Checkbox's accept a child, which is rendered as the label of the checkbox. + +```python +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. + +```python +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. + + +```python +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. + +```python +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 + +```python +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. + +```python +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 + +```{eval-rst} +.. dhautofunction:: deephaven.ui.checkbox +``` diff --git a/plugins/ui/src/deephaven/ui/components/checkbox.py b/plugins/ui/src/deephaven/ui/components/checkbox.py index d8bb1029d..be74ab9e4 100644 --- a/plugins/ui/src/deephaven/ui/components/checkbox.py +++ b/plugins/ui/src/deephaven/ui/components/checkbox.py @@ -153,6 +153,9 @@ def checkbox( aria_errormessage: The id of the element that provides error information for the current element. UNSAFE_class_name: A CSS class to apply to the element. UNSAFE_style: A CSS style to apply to the element. + + Returns: + The rendered checkbox. """ return component_element(