# Checkbox Group

Checkbox group areas allow the selection of one or more items from a list of choices, represented by checkboxes.

## Example

```python
from deephaven import ui


my_checkbox_group_basic = ui.checkbox_group(
    "Soccer",
    "Basketball",
    "Baseball",
    label="Favourite Sports",
)
```

## UI Recommendations

Recommendations for creating checkbox groups:

1. Every checkbox group should have a [label]() specified. Without one, the checkbox group 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. While labels can be placed either on top or on the side of the checkbox groups, top labels are the default recommendation. Top labels work better with longer copy, localization, and responsive layouts. Side labels are more useful when vertical space is limited.
3. Checkbox groups can be either horizontal or vertical. By default, they are vertical; the orientation should only be horizontal if vertical space is limited.
4. Checkbox groups can be marked as optional or required, with required groups indicated by either a “(required)” label or an asterisk icon, which should be accompanied by help text.
5. Checkbox groups should use help text for error messaging and descriptions, providing context for why a selection is required or clarifying the options.

Consider using [`checkbox_group`]() to select or mark a single item as selected.

## Content

Checkbox groups accept checkboxes and primitive types as children. Checkboxes accept a child, which is rendered as the checkbox’s label.

```python
from deephaven import ui


my_checkbox_group_content_example = ui.checkbox_group(
    "Soccer",
    ui.checkbox("Basketball"),
    label="Favourite Sports",
)
```

## Value

Checkbox groups allow selecting zero or more items, with initial values set via `default_value` or controlled values via `value`.

```python
from deephaven import ui


@ui.component
def ui_checkbox_group_value_examples():
    value, set_value = ui.use_state(["Soccer"])
    return [
        ui.checkbox_group(
            "Soccer",
            "Basketball",
            "Baseball",
            label="Favourite Sports (uncontrolled)",
            default_value=["Soccer", "Baseball"],
        ),
        ui.checkbox_group(
            "Soccer",
            "Basketball",
            "Baseball",
            label="Favourite Sports (controlled)",
            value=value,
            on_change=set_value,
        ),
    ]


my_checkbox_group_value_examples = ui_checkbox_group_value_examples()
```

## HTML Forms

Checkbox groups 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_group(ui.checkbox("Sample Label"), name="Sample Name")
)
```

## Labeling

The checkbox group can be labeled using the `label` prop, and if no label is provided, an `aria_label` must be provided to identify the control for accessibility purposes.

```python
from deephaven import ui


@ui.component
def ui_checkbox_group_label_examples():
    return [
        ui.checkbox_group(
            ui.checkbox("Wizard", value="wizard"),
            ui.checkbox("Dragon", value="dragon"),
            label="Favorite avatars",
        ),
        ui.checkbox_group(
            ui.checkbox("Wizard", value="wizard"),
            ui.checkbox("Dragon", value="dragon"),
            aria_label="Favorite avatars",
        ),
    ]


my_checkbox_group_label_examples = ui_checkbox_group_label_examples()
```

The `is_required` prop and the `necessity_indicator` props can be used to show whether selecting an option in the checked group is required or optional.

When the `necessity_indicator` prop is set to “label”, a localized string will be generated for “(required)” or “(optional)” automatically.

```python
from deephaven import ui


@ui.component
def ui_checkbox_group_required_examples():
    return [
        ui.checkbox_group(
            ui.checkbox("Wizard", value="wizard"),
            ui.checkbox("Dragon", value="dragon"),
            label="Favorite avatars",
            is_required=True,
        ),
        ui.checkbox_group(
            ui.checkbox("Wizard", value="wizard"),
            ui.checkbox("Dragon", value="dragon"),
            label="Favorite avatars",
            is_required=True,
            necessity_indicator="label",
        ),
        ui.checkbox_group(
            ui.checkbox("Wizard", value="wizard"),
            ui.checkbox("Dragon", value="dragon"),
            label="Favorite avatars",
            necessity_indicator="label",
        ),
    ]


my_checkbox_group_required_examples = ui_checkbox_group_required_examples()
```

## Events

Checkbox groups accept an `on_change` prop, triggered whenever a checkbox within the group is clicked.

```python
from deephaven import ui


@ui.component
def ui_checkbox_group_event_example():
    selected, set_selected = ui.use_state(["Soccer"])
    return [
        ui.checkbox_group(
            "Soccer",
            "Basketball",
            "Baseball",
            label="Favourite Sports (controlled)",
            value=selected,
            on_change=set_selected,
        ),
        f"You have selected: {selected}!",
    ]


my_checkbox_group_event_example = ui_checkbox_group_event_example()
```

To require specific checkboxes to be checked, set the `is_required` prop at the Checkbox level, not the Checkbox Group.

```python
from deephaven import ui


my_checkbox_group_individual_validation_example = ui.form(
    ui.checkbox_group(
        ui.checkbox("Terms and conditions", value="terms", is_required=True),
        ui.checkbox("Privacy policy", value="privacy", is_required=True),
        label="Agree to the following",
        is_required=True,
    ),
    ui.button_group(
        ui.button("Submit", type="submit", variant="primary"),
        ui.button("Reset", type="reset", variant="secondary"),
    ),
    on_submit=lambda: print("Form submitted!"),
    validation_behavior="native",
)
```

## Orientation

While aligned vertically by default, the axis with which the checkboxes align can be changed via the `orientation` prop.

```python
from deephaven import ui


my_checkbox_group_orientation_example = ui.checkbox_group(
    ui.checkbox("Wizard", value="wizard"),
    ui.checkbox("Dragon", value="dragon"),
    label="Favorite avatars",
    orientation="horizontal",
)
```

## Label position

By default, the position of a checkbox group’s label is above the checkbox group, but it can be changed to the side using the `label_position` prop.

```python
from deephaven import ui


my_checkbox_group_label_position_example = ui.checkbox_group(
    ui.checkbox("Wizard", value="wizard"),
    ui.checkbox("Dragon", value="dragon"),
    label="Favorite avatars",
    label_position="side",
)
```

## Help text

A checkbox group can have both a `description` and an `error_message`. The error message should offer specific guidance on how to correct the input.

The `is_invalid` prop can be used to set whether the current checkbox group state is valid or invalid.

```python
from deephaven import ui


@ui.component
def ui_checkbox_group_help_text_examples():
    return [
        ui.checkbox_group(
            "Soccer",
            "Basketball",
            "Baseball",
            label="Favourite sports",
            description="Select an avatar from the two options.",
        ),
        ui.checkbox_group(
            "Soccer",
            "Basketball",
            "Baseball",
            label="Favourite sports",
            description="Select favourite sports from the two options.",
            error_message="Sample invalid error message.",
            is_invalid=True,
        ),
    ]


my_checkbox_group_help_text_examples = ui_checkbox_group_help_text_examples()
```

## Contextual Help

Using the `contextual_help` prop, a `ui.contextual_help` can be placed next to the label to provide additional information about the checkbox group.

```python
from deephaven import ui


my_checkbox_group_contextual_help_example = ui.checkbox_group(
    "Soccer",
    "Basketball",
    "Baseball",
    label="Favorite sports",
    contextual_help=ui.contextual_help(ui.heading("Content tips")),
)
```

## Disabled state

The `is_disabled` prop disables a checkbox group to prevent user interaction. This is useful when the checkbox group should be visible but not available for selection.

```python
from deephaven import ui


my_checkbox_group_is_disabled_example = ui.checkbox_group(
    "Soccer",
    "Basketball",
    "Baseball",
    label="Favorite sports",
    is_disabled=True,
)
```

## Read only

The `is_read_only` prop makes checkbox groups read-only to prevent user interaction. This is different from setting the `is_disabled` prop since the checkbox group remains focusable and its options remain visible.

```python
from deephaven import ui


my_checkbox_group_is_read_only_example = ui.checkbox_group(
    "Soccer",
    "Basketball",
    "Baseball",
    label="Favorite sports",
    is_read_only=True,
)
```

## Emphasized

The `is_emphasized` prop makes the selected checkbox the user’s accent color, adding a visual prominence to the selection.

```python
from deephaven import ui


my_checkbox_group_is_emphasized_example = ui.checkbox_group(
    "Soccer",
    "Basketball",
    "Baseball",
    label="Favorite sports",
    is_emphasized=True,
)
```

## API Reference

A grouping of checkbox's that are related to each other.

**Returns:** `Element` The rendered checkbox group element.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "checkbox_group", "parameters": [{"name": "*children", "type": "Any", "description": "The children of the checkbox group."}, {"name": "orientation", "type": "Literal['horizontal', 'vertical']", "description": "The axis the CheckboxGroup should align with.", "default": "'vertical'"}, {"name": "is_emphasized", "type": "bool | None", "description": "Whether the checkbox's should be displayed with emphasized style.", "default": "None"}, {"name": "value", "type": "Sequence[str | int | float | bool] | None", "description": "The selected checkbox within the checkbox group (controlled).", "default": "None"}, {"name": "default_value", "type": "Sequence[str | int | float | bool] | None", "description": "The default selected checkbox within the checkbox group (uncontrolled).", "default": "None"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the checkbox group is disabled.", "default": "None"}, {"name": "is_read_only", "type": "bool | None", "description": "Whether the checkbox group is read only.", "default": "None"}, {"name": "name", "type": "str | None", "description": "The name of the input element, used when submitting an HTML form.", "default": "None"}, {"name": "label", "type": "Any | None", "description": "The label of the checkbox group.", "default": "None"}, {"name": "description", "type": "Any | None", "description": "A description for the checkbox group. Provides a hint such as specific requirements for what to choose.", "default": "None"}, {"name": "error_message", "type": "Any | None", "description": "An error message to be displayed when the checkbox group is an errored state.", "default": "None"}, {"name": "is_required", "type": "bool | None", "description": "Whether user input is required on the input before form submission.", "default": "None"}, {"name": "is_invalid", "type": "bool | None", "description": "Whether the checkbox group is in an invalid state.", "default": "None"}, {"name": "validation_behavior", "type": "Literal['aria', 'native'] | None", "description": "Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.", "default": "'aria'"}, {"name": "label_position", "type": "str | None", "description": "The label's overall position relative to the element it is labeling.", "default": "None"}, {"name": "label_align", "type": "str | None", "description": "The label's horizontal alignment relative to the element it is labeling.", "default": "None"}, {"name": "necessity_indicator", "type": "str | None", "description": "Whether the required state should be shown as an icon or text.", "default": "None"}, {"name": "contextual_help", "type": "Any | None", "description": "A ContextualHelp element to place next to the label.", "default": "None"}, {"name": "show_error_icon", "type": "bool | None", "description": "Whether an error icon is rendered.", "default": "None"}, {"name": "on_change", "type": "Callable[[str | int | float | bool], None] | None", "description": "Handler that is called when the selection changes.", "default": "None"}, {"name": "on_focus", "type": "Callable[[FocusEvent], None] | None", "description": "Handler that is called when the element receives focus.", "default": "None"}, {"name": "on_blur", "type": "Callable[[FocusEvent], None] | None", "description": "Handler that is called when the element loses focus.", "default": "None"}, {"name": "on_focus_change", "type": "Callable[[bool], None] | None", "description": "Handler that is called when the element's focus status 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": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width 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": "Specifies how the element is position.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The top position of the element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The bottom position of the element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The left position of the element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The right position of the element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The logical start position of the element, depending on layout direction.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The logical end position of the element, depending on layout direction.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stacking order for the element", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Hides the element.", "default": "None"}, {"name": "id", "type": "str | None", "description": "The unique identifier of the element.", "default": "None"}, {"name": "aria_label", "type": "str | None", "description": "Defines a string value that labels the current element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "Identifies the element (or elements) that labels the current element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "Identifies the element (or elements) that describes the object.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "Identifies the element (or elements) that provide a detailed, extended description for the object.", "default": "None"}, {"name": "aria_errormessage", "type": "str | None", "description": "Identifies the element that provides an error message for the object.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "Set the CSS className for the element. Only use as a last resort. Use style props instead.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "Set the inline style for the element. Only use as a last resort. Use style props instead.", "default": "None"}]}} />