# Combo Box

Combo boxes combine a text input field with a picker menu, enabling users to filter and select from longer lists based on their query.

## Example

```python
from deephaven import ui


@ui.component
def ui_combo_box_basic():
    option, set_option = ui.use_state("")

    return ui.combo_box(
        ui.item("red panda"),
        ui.item("cat"),
        ui.item("dog"),
        ui.item("aardvark"),
        ui.item("kangaroo"),
        ui.item("snake"),
        ui.item("ant"),
        label="Favorite Animal",
        selected_key=option,
        on_change=set_option,
    )


my_combo_box_basic = ui_combo_box_basic()
```

## UI Recommendations

Recommendations for creating clear and effective combo boxes:

1. The combo box’s text input simplifies searching through large lists. For lists with fewer than 6 items, use radio buttons. For lists with more than 6 items, assess if the list is complex enough to need searching and filtering, and if not, use a picker instead.
2. Every combo box should have a label specified. Without one, the combo box is ambiguous and not accessible.
3. Options in the combo box should be kept short and concise; multiple lines are strongly discouraged. If more than one line is needed, consider using a description to add context to the option.
4. Choose a `width` for your combo boxes that can accommodate most of the available options.
5. The field labels, menu items, and placeholder text should all be in sentence case.
6. Identify which combo boxes are required or optional, and use the `is_required` field or the `necessity_indicator` to mark them accordingly.
7. A combo box’s help text should provide actionable guidance on what to select and how to select it, offering additional context without repeating the placeholder text.
8. When an error occurs, the help text specified in a combo box is replaced by error text; thus, ensure both help and error text convey the same essential information to maintain consistent messaging and prevent loss of critical details.
9. Write error messages in a clear, concise, and helpful manner, guiding users to resolve the issue without ambiguity; ideally, they should be 1-2 short, complete sentences.

## Data sources

For combo boxes, we can use a Deephaven table as a data source to populate the options. When using a table, it automatically uses the first column as both the key and label. If there are any duplicate keys, an error will be thrown; to avoid this, a `select_distinct` can be used on the table prior to using it as a combo box data source.

```python
from deephaven import ui, empty_table
from deephaven.plot import express as dx


countries = dx.data.gapminder().select_distinct("Country")


my_combo_box_table_source_example = ui.combo_box(countries, label="Sample Combo box")
```

## Item table sources

If you wish to manually specify the keys and labels, use a `ui.item_table_source` to dynamically derive the options from a table.

```python
from deephaven import ui, empty_table

account_icon = "vsAccount"
columns = [
    "Key=new Integer(i)",
    "Label=new String(`Display `+i)",
    "Icon=(String) account_icon",
]
column_types = empty_table(20).update(columns)


item_table_source = ui.item_table_source(
    column_types,
    key_column="Key",
    label_column="Label",
    icon_column="Icon",
)


my_combo_box_item_table_source_example = ui.combo_box(
    item_table_source, label="User Combo box"
)
```

## Custom Value

By default, when a combo box loses focus, it resets its input value to match the selected option’s text or clears the input if no option is selected. To allow users to enter a custom value, use the `allows_custom_value` prop to override this behavior.

```python
from deephaven import ui
from deephaven.plot import express as dx

countries = dx.data.gapminder().select_distinct("Country")


@ui.component
def ui_combo_box_custom_value_examples():
    value, set_value = ui.use_state("")
    value_2, set_value_2 = ui.use_state("")
    return [
        ui.combo_box(
            countries,
            on_input_change=set_value,
            allows_custom_value=True,
            label="Allows custom value",
        ),
        ui.text_field(value=value),
        ui.combo_box(
            countries,
            on_input_change=set_value_2,
            allows_custom_value=False,
            label="Does not allow custom value",
        ),
        ui.text_field(value=value_2),
    ]


my_combo_box_custom_value_examples = ui_combo_box_custom_value_examples()
```

## HTML Forms

Combo boxes can support a `name` prop for integration with HTML forms, allowing for easy identification of a value on form submission. The `form_value` prop determines whether the text or key of the selected item is submitted in an HTML form; if `allows_custom_value` is true, only the text is submitted.

```python
from deephaven import ui


@ui.component
def ui_combo_box_form_examples():
    return [
        ui.form(
            ui.combo_box(
                ui.item("Chocolate"),
                ui.item("Mint"),
                ui.item("Vanilla"),
                ui.item("Strawberry"),
                ui.item("Cookies and Cream"),
                ui.item("Coffee"),
                ui.item("Mango"),
                label="Ice cream flavor",
                allows_custom_value=True,
            ),
            ui.combo_box(
                ui.item("Panda"),
                ui.item("Cat"),
                ui.item("Dog"),
                ui.item("Hamster"),
                ui.item("Rabbit"),
                ui.item("Horse"),
                label="Favourite Animal",
                name="favouriteAnimalId",
            ),
            ui.button("Submit", type="submit"),
            on_submit=lambda event: print(event),
        )
    ]


my_combo_box_form_examples = ui_combo_box_form_examples()
```

## Labeling

The combo box 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_combo_box_label_examples():
    return [
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            label="Pick an option",
        ),
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            aria_label="Pick an option",
        ),
    ]


my_combo_box_label_examples = ui_combo_box_label_examples()
```

The `is_required` prop and the `necessity_indicator` props can be used to show whether selecting an option in the combo box 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_combo_box_required_examples():
    return [
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            label="Pick an option",
            is_required=True,
        ),
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            label="Pick an option",
            is_required=True,
            necessity_indicator="label",
        ),
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            label="Pick an option",
            necessity_indicator="label",
        ),
    ]


my_combo_box_required_examples = ui_combo_box_required_examples()
```

## Selection

In a combo box, the `default_selected_key` or `selected_key` props set a selected option.

The `default_selected_key` is useful for simpler scenarios where you don’t need to control the state externally. The `selected_key` is used for scenarios where the state should be managed by the parent component, providing control and flexibility over the selection of the combo box.

```python
from deephaven import ui


@ui.component
def ui_combo_box_selected_key_examples():
    option, set_option = ui.use_state("Option 1")
    return [
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            default_selected_key="Option 2",
            label="Pick an option (uncontrolled)",
        ),
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            selected_key=option,
            on_change=set_option,
            label="Pick an option (controlled)",
        ),
    ]


my_combo_box_selected_key_examples = ui_combo_box_selected_key_examples()
```

## Sections

Combo boxes support sections to group options. Sections can be used by wrapping groups of items in a Section element. Each Section takes a title and key prop.

Note that, when searching for options, searching by section will not result in the respective options within that section appearing.

Also, sections can only be used directly, not from a table data source.

```python
from deephaven import ui


my_combo_box_section_example = ui.combo_box(
    ui.section(
        ui.item("Option 1"),
        ui.item("Option 2"),
        ui.item("Option 3"),
        ui.item("Option 4"),
        ui.item("Option 5"),
        ui.item("Option 6"),
        ui.item("Option 7"),
        ui.item("Option 8"),
        title="Section 1",
    ),
    ui.section(
        ui.item("Option 9"),
        ui.item("Option 10"),
        ui.item("Option 11"),
        ui.item("Option 12"),
        ui.item("Option 13"),
        ui.item("Option 14"),
        ui.item("Option 15"),
        ui.item("Option 16"),
        title="Section 2",
    ),
)
```

## Events

Combo boxes support selection via mouse, keyboard, and touch. You can handle all these via the `on_change` prop, which receives the selected key as an argument. Additionally, combo boxes accept an `on_input_change` prop, which is triggered whenever the search value is edited by the user, whether through typing or option selection.

Each interaction done in the combo box will trigger its associated event handler. For instance, typing in the input field will only trigger the `on_input_change`, not the `on_change`.

Note, this is not the case for selections; when a selection is made, both the `on_change` and `on_input_change` are triggered.

```python
from deephaven import ui


@ui.component
def ui_combo_box_control_example():
    input_value, set_input_value = ui.use_state("")
    selection_state, set_selection_state = ui.use_state("")

    def handle_input_change(new_value):
        set_selection_state("")
        set_input_value(new_value)
        print(f"Text changed to {input_value}")

    def handle_selection_change(new_value):
        set_input_value(new_value)
        set_selection_state(new_value)
        print(f"Selection changed to {selection_state}")

    return [
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            input_value=input_value,
            on_input_change=handle_input_change,
            selected_key=selection_state,
            on_change=handle_selection_change,
        )
    ]


my_combo_box_control_example = ui_combo_box_control_example()
```

## Complex items

Items within a combo box can include additional content to better convey options. You can add icons, avatars, and descriptions to the children of an `ui.item`. When adding a description, set the `slot` prop to “description” to differentiate between the text elements.

```python
from deephaven import ui


my_combo_box_complex_items_example = ui.combo_box(
    ui.item(
        ui.icon("vsGithubAlt"),
        ui.text("Github"),
        ui.text("Github Option", slot="description"),
        text_value="Github",
    ),
    ui.item(
        ui.icon("vsAzureDevops"),
        ui.text("Azure"),
        ui.text("Azure Option", slot="description"),
        text_value="Azure",
    ),
)
```

## Validation

The `is_required` prop ensures that the user selects an option. The related `validation_behaviour` prop allows the user to specify aria or native verification.

When the prop is set to “native”, the validation errors block form submission and are displayed as help text automatically.

```python
from deephaven import ui


@ui.component
def ui_combo_box_validation_behaviour_example():
    return ui.form(
        ui.combo_box(
            ui.section(ui.item("Option 1"), ui.item("Option 2"), title="Section 1"),
            validation_behavior="aria",
            is_required=True,
        )
    )


my_combo_box_validation_behaviour_example = ui_combo_box_validation_behaviour_example()
```

## Trigger Options

By default, the combo box’s menu opens when the user types into the input field (“input”). This behavior can be changed to open on focus (“focus”) or only when the field button is clicked (“manual”) using the `menu_trigger` prop.

```python
from deephaven import ui


@ui.component
def ui_combo_box_trigger_option_examples():
    return [
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            label="Select Option",
        ),
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            label="Select Option",
            menu_trigger="focus",
        ),
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            label="Select Option",
            menu_trigger="manual",
        ),
    ]


my_combo_box_trigger_option_examples = ui_combo_box_trigger_option_examples()
```

## Label position

By default, the position of a combo box’s label is above the combo box, but it can be moved to the side using the `label_position` prop.

```python
from deephaven import ui


@ui.component
def ui_combo_box_label_position_examples():
    return [
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            label="Test Label",
        ),
        ui.combo_box(
            ui.item("Option 1"),
            ui.item("Option 2"),
            ui.item("Option 3"),
            ui.item("Option 4"),
            ui.item("Option 5"),
            ui.item("Option 6"),
            ui.item("Option 7"),
            ui.item("Option 8"),
            ui.item("Option 9"),
            label="Test Label",
            label_position="side",
        ),
    ]


my_combo_box_label_position_examples = ui_combo_box_label_position_examples()
```

## Quiet State

The `is_quiet` prop makes a combo box “quiet”. This can be useful when the combo box and its corresponding styling should not distract users from surrounding content.

```python
from deephaven import ui


my_combo_box_is_quiet_example = ui.combo_box(
    ui.item("Option 1"),
    ui.item("Option 2"),
    ui.item("Option 3"),
    ui.item("Option 4"),
    ui.item("Option 5"),
    ui.item("Option 6"),
    ui.item("Option 7"),
    ui.item("Option 8"),
    ui.item("Option 9"),
    is_quiet=True,
)
```

## Disabled State

The `is_disabled` prop disables a combo box to prevent user interaction. This is useful when the combo box should be visible but unavailable for selection.

```python
from deephaven import ui


my_combo_box_is_disabled_example = ui.combo_box(
    ui.item("Option 1"),
    ui.item("Option 2"),
    ui.item("Option 3"),
    ui.item("Option 4"),
    ui.item("Option 5"),
    ui.item("Option 6"),
    ui.item("Option 7"),
    ui.item("Option 8"),
    ui.item("Option 9"),
    is_disabled=True,
)
```

## Read-only State

The `is_read_only` prop prevents user input in a combo box, but the selected option should be visible.

```python
from deephaven import ui


my_combo_box_is_read_only_example = ui.combo_box(
    ui.item("Option 1", key="Option 1"),
    ui.item("Option 2", key="Option 2"),
    ui.item("Option 3", key="Option 3"),
    ui.item("Option 4", key="Option 4"),
    ui.item("Option 5", key="Option 5"),
    ui.item("Option 6", key="Option 6"),
    ui.item("Option 7", key="Option 7"),
    ui.item("Option 8", key="Option 8"),
    default_selected_key="Option 1",
    is_read_only=True,
)
```

## Help text

A combo box can have both a `description` and an `error_message`. The description remains visible at all times. Use the error message to offer specific guidance on how to correct the input.

```python
from deephaven import ui


@ui.component
def ui_combo_box_help_text_examples():
    return [
        ui.combo_box(
            ui.section(
                ui.item("Option 1", key="Option 1"),
                ui.item("Option 2", key="Option 2"),
                ui.item("Option 3", key="Option 3"),
                ui.item("Option 4", key="Option 4"),
                ui.item("Option 5", key="Option 5"),
                ui.item("Option 6", key="Option 6"),
                ui.item("Option 7", key="Option 7"),
                ui.item("Option 8", key="Option 8"),
                title="Section 1",
            ),
            label="Sample Label",
            description="Enter a comment.",
        ),
        ui.combo_box(
            ui.section(
                ui.item("Option 1", key="Option 1"),
                ui.item("Option 2", key="Option 2"),
                ui.item("Option 3", key="Option 3"),
                ui.item("Option 4", key="Option 4"),
                ui.item("Option 5", key="Option 5"),
                ui.item("Option 6", key="Option 6"),
                ui.item("Option 7", key="Option 7"),
                ui.item("Option 8", key="Option 8"),
                title="Section 1",
            ),
            label="Sample Label",
            validation_state="invalid",
            error_message="Sample invalid error message.",
        ),
    ]


my_combo_box_help_text_examples = ui_combo_box_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 combo box.

```python
from deephaven import ui


my_combo_box_contextual_help_example = ui.combo_box(
    ui.section(
        ui.item("Option 1"),
        ui.item("Option 2"),
        ui.item("Option 3"),
        ui.item("Option 4"),
        ui.item("Option 5"),
        ui.item("Option 6"),
        ui.item("Option 7"),
        ui.item("Option 8"),
        title="Section 1",
    ),
    label="Sample Label",
    contextual_help=ui.contextual_help(ui.heading("Content tips")),
)
```

## Custom width

The `width` prop adjusts the width of a combo box, and the `max_width` prop enforces a maximum width.

```python
from deephaven import ui


@ui.component
def ui_combo_box_width_examples():
    return [
        ui.combo_box(
            ui.item("Option 1", key="Option 1"),
            ui.item("Option 2", key="Option 2"),
            ui.item("Option 3", key="Option 3"),
            ui.item("Option 4", key="Option 4"),
            ui.item("Option 5", key="Option 5"),
            ui.item("Option 6", key="Option 6"),
            ui.item("Option 7", key="Option 7"),
            ui.item("Option 8", key="Option 8"),
            width="size-3600",
        ),
        ui.combo_box(
            ui.item("Option 1", key="Option 1"),
            ui.item("Option 2", key="Option 2"),
            ui.item("Option 3", key="Option 3"),
            ui.item("Option 4", key="Option 4"),
            ui.item("Option 5", key="Option 5"),
            ui.item("Option 6", key="Option 6"),
            ui.item("Option 7", key="Option 7"),
            ui.item("Option 8", key="Option 8"),
            width="size-3600",
            max_width="100%",
        ),
    ]


my_combo_box_width_examples = ui_combo_box_width_examples()
```

## Align and Direction

The `align` prop sets the text alignment of the options in the combo box, while the `direction` prop specifies which direction the menu will open.

```python
from deephaven import ui


@ui.component
def ui_combo_box_alignment_direction_examples():
    return ui.view(
        ui.flex(
            ui.combo_box(
                ui.item("Option 1"),
                ui.item("Option 2"),
                ui.item("Option 3"),
                ui.item("Option 4"),
                ui.item("Option 5"),
                ui.item("Option 6"),
                ui.item("Option 7"),
                ui.item("Option 8"),
                align="end",
                menu_width="size-3000",
            ),
            ui.combo_box(
                ui.item("Option 1"),
                ui.item("Option 2"),
                ui.item("Option 3"),
                ui.item("Option 4"),
                ui.item("Option 5"),
                ui.item("Option 6"),
                ui.item("Option 7"),
                ui.item("Option 8"),
                direction="top",
            ),
            gap="size-150",
            direction="column",
        ),
        padding=40,
    )


my_combo_box_alignment_direction_examples = ui_combo_box_alignment_direction_examples()
```

## API Reference

A combo box that can be used to search or select from a list. Children should be one of five types:
1. If children are of type Item, they are the dropdown options.
2. If children are of type SectionElement, they are the dropdown sections.
3. If children are of type Table, the values in the table are the dropdown options.

**Returns:** `BaseElement` The rendered ComboBox.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "combo_box", "parameters": [{"name": "*children", "type": "str | int | float | bool | BaseElement | Element | Table | PartitionedTable | ItemTableSource", "description": "The options to render within the combo box."}, {"name": "menu_trigger", "type": "Literal['focus', 'input', 'manual'] | None", "description": "The interaction required to display the ComboBox menu.", "default": "'input'"}, {"name": "is_quiet", "type": "bool | None", "description": "Whether the ComboBox should be displayed with a quiet style.", "default": "None"}, {"name": "align", "type": "Literal['start', 'end'] | None", "description": "Alignment of the menu relative to the input target.", "default": "'end'"}, {"name": "direction", "type": "Literal['bottom', 'top'] | None", "description": "Direction the menu will render relative to the ComboBox.", "default": "'bottom'"}, {"name": "loading_state", "type": "Literal['loading', 'sorting', 'loadingMore', 'error', 'idle', 'filtering'] | None", "description": "The current loading state of the ComboBox. Determines whether or not the progress circle should be shown.", "default": "None"}, {"name": "should_flip", "type": "bool", "description": "Whether the menu should automatically flip direction when space is limited.", "default": "True"}, {"name": "menu_width", "type": "str | float | None", "description": "Width of the menu. By default, matches width of the combobox. Note that the minimum width of the dropdown is always equal to the combobox's width.", "default": "None"}, {"name": "form_value", "type": "Literal['key', 'text'] | None", "description": "Whether the text or key of the selected item is submitted as part of an HTML form. When allowsCustomValue is true, this option does not apply and the text is always submitted.", "default": "'text'"}, {"name": "should_focus_wrap", "type": "bool | None", "description": "Whether keyboard navigation is circular.", "default": "None"}, {"name": "input_value", "type": "str | None", "description": "The value of the search input (controlled).", "default": "None"}, {"name": "default_input_value", "type": "str | None", "description": "The default value of the search input (uncontrolled).", "default": "None"}, {"name": "allows_custom_value", "type": "bool | None", "description": "Whether the ComboBox allows a non-item matching input value to be set.", "default": "None"}, {"name": "disabled_keys", "type": "list[str | int | float | bool] | None", "description": "The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.", "default": "None"}, {"name": "selected_key", "type": "str | int | float | bool | None", "description": "The currently selected key in the collection (controlled).", "default": "None"}, {"name": "default_selected_key", "type": "str | int | float | bool | None", "description": "The initial selected key in the collection (uncontrolled).", "default": "None"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the input is disabled.", "default": "None"}, {"name": "is_read_only", "type": "bool | None", "description": "Whether the input can be selected but not changed by the user.", "default": "None"}, {"name": "is_required", "type": "bool | None", "description": "Whether user input is required on the input before form submission.", "default": "None"}, {"name": "validation_behavior", "type": "Literal['aria', 'native']", "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": "auto_focus", "type": "bool | None", "description": "Whether the element should receive focus on render.", "default": "None"}, {"name": "label", "type": "Element | None", "description": "The content to display as the label.", "default": "None"}, {"name": "description", "type": "Element | None", "description": "A description for the field. Provides a hint such as specific requirements for what to choose.", "default": "None"}, {"name": "error_message", "type": "Element | None", "description": "An error message for the field.", "default": "None"}, {"name": "name", "type": "str | None", "description": "The name of the input element, used when submitting an HTML form.", "default": "None"}, {"name": "validation_state", "type": "Literal['valid', 'invalid'] | None", "description": "Whether the input should display its \"valid\" or \"invalid\" visual styling.", "default": "None"}, {"name": "label_position", "type": "Literal['top', 'side']", "description": "The label's overall position relative to the element it is labeling.", "default": "'top'"}, {"name": "label_align", "type": "Literal['start', 'end'] | None", "description": "The label's horizontal alignment relative to the element it is labeling.", "default": "None"}, {"name": "necessity_indicator", "type": "Literal['icon', 'label'] | None", "description": "Whether the required state should be shown as an icon or text.", "default": "None"}, {"name": "contextual_help", "type": "Element | None", "description": "A ContextualHelp element to place next to the label.", "default": "None"}, {"name": "on_open_change", "type": "Callable[[bool, Literal['focus', 'input', 'manual']], None] | None", "description": "Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.", "default": "None"}, {"name": "on_selection_change", "type": "Callable[[str | int | float | bool], None] | None", "description": "Handler that is called when the selection changes.", "default": "None"}, {"name": "on_change", "type": "Callable[[str | int | float | bool], None] | None", "description": "Alias of on_selection_change. Handler that is called when the selection changes.", "default": "None"}, {"name": "on_input_change", "type": "Callable[[str], None] | None", "description": "Handler that is called when the ComboBox input value changes.", "default": "None"}, {"name": "on_focus", "type": "Callable[[Callable[[FocusEvent], None]], None] | None", "description": "Handler that is called when the element receives focus.", "default": "None"}, {"name": "on_blur", "type": "Callable[[Callable[[FocusEvent], None]], 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": "on_key_down", "type": "Callable[[Callable[[KeyboardEvent], None]], None] | None", "description": "Handler that is called when a key is pressed.", "default": "None"}, {"name": "on_key_up", "type": "Callable[[Callable[[KeyboardEvent], None]], None] | None", "description": "Handler that is called when a key is released.", "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 much 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 much 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 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 align_items 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": "Specifies 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": "The name of the grid area to place the element in.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "The name of the grid row to place the element in.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "The name of the grid row to start the element in.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "The name of the grid row to end the element in.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "The name of the grid column to place the element in.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "The name of the grid column to start the element in.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "The name of the grid column to end the element in.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin to apply around the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin to apply above the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin to apply below the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin to apply before the element.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin to apply after the element.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin to apply to the left and right of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin to apply to the top and bottom 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 positioned.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The distance from the top of the containing element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The distance from the bottom of the containing element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The distance from the start of the containing element.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The distance from the left of the containing element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The distance from the right of the containing element.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stack order of the element.", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Whether the element is hidden.", "default": "None"}, {"name": "id", "type": "str | None", "description": "A unique identifier for the element.", "default": "None"}, {"name": "aria_label", "type": "str | None", "description": "The label for the element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "The id of the element that labels the element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "The id of the element that describes the element.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "The details for the element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "A CSS class to apply to the element.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "A CSS style to apply to the element.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />