# Form

Forms allow users to enter data that can be submitted while providing alignment and styling for form fields.

## Example

```python
from deephaven import ui


@ui.component
def ui_form():
    return ui.form(
        ui.text_field(name="name", label="Enter name"),
        ui.button("Submit", type="submit"),
    )


my_form = ui_form()
```

## Events

Forms can handle three events:

1. **Submit**: Triggered when the form is submitted. Users can define a callback function to handle the form data upon submission.
2. **Reset**: Triggered when the form is reset. This event can be used to clear the form fields or reset them to their initial values.
3. **Invalid**: Triggered when the form validation fails. This event allows users to handle validation errors and provide feedback.

### Submit

```python
from deephaven import ui


@ui.component
def ui_form_submit():
    return ui.form(
        ui.text_field(name="name", label="Enter name"),
        ui.number_field(name="age", label="Enter age"),
        ui.button("Submit", type="submit"),
        on_submit=lambda e: print(f"Form submitted: {e}"),
    )


my_form_submit = ui_form_submit()
```

### Reset

```python
from deephaven import ui


@ui.component
def ui_form_submit():
    return ui.form(
        ui.text_field(name="name", label="Enter name"),
        ui.number_field(name="age", label="Enter age"),
        ui.button("Reset", type="reset"),
        on_reset=lambda e: print(f"Form reset"),
    )


my_form_submit = ui_form_submit()
```

### Invalid

```python
from deephaven import ui


@ui.component
def ui_form_invalid():
    value, set_value = ui.use_state("")
    return ui.form(
        ui.text_field(
            name="name",
            label="Enter name",
            value=value,
            on_change=set_value,
            is_required=True,
        ),
        ui.number_field(name="age", label="Enter age"),
        ui.button("Submit", type="submit"),
        on_invalid=lambda e: print(f"Form invalid"),
        validation_behavior="native",
    )


my_form_invalid = ui_form_invalid()
```

## Action

The `action` prop enables forms to be sent to a URL. The example below communicates with a 3rd party server and displays the content received from the form.

```python
from deephaven import ui


@ui.component
def ui_form_action():
    return ui.form(
        ui.text_field(name="first_name", default_value="Mickey", label="First Name"),
        ui.text_field(name="last_name", default_value="Mouse", label="Last Name"),
        ui.button("Submit", type="submit"),
        action="https://postman-echo.com/get",
        method="get",
        target="_blank",
    )


my_form_action = ui_form_action()
```

## Validation Behavior

By default, validation errors will be displayed in real-time as the fields are edited, but form submission is not blocked. To enable this and native HTML form validation, set `validation_behavior` to “native”.

```python
from deephaven import ui


@ui.component
def ui_form_validation_behavior():
    return ui.form(
        ui.text_field(name="email", label="Email", type="email", is_required=True),
        ui.button("Submit", type="submit"),
        validation_behavior="native",
    )


my_form_validation_behavior = ui_form_validation_behavior()
```

## Quiet

The `is_quiet` prop makes form fields “quiet”. This can be useful when its corresponding styling should not distract users from surrounding content.

```python
from deephaven import ui


@ui.component
def ui_form_quiet():

    return ui.form(
        ui.text_field(name="name", label="Enter name"),
        is_quiet=True,
    )


my_form_quiet = ui_form_quiet()
```

## Emphasized

The `is_emphasized` prop adds visual prominence to the form fields. This can be useful when its corresponding styling should catch the user’s attention.

```python
from deephaven import ui


@ui.component
def ui_form_emphasized():

    return ui.form(
        ui.text_field(name="name", label="Enter name"),
        ui.radio_group(
            ui.radio("Video games", value="games"),
            ui.radio("Reading", value="reading"),
            ui.radio("Sports", value="sports"),
            label="Favorite hobby",
            default_value="games",
        ),
        is_emphasized=True,
    )


my_form = ui_form_emphasized()
```

## Disabled

The `is_disabled` prop disables form fields to prevent user interaction. This is useful when the fields should be visible but not available for input.

```python
from deephaven import ui


@ui.component
def ui_form_disabled():
    return ui.form(
        ui.text_field(name="name", label="Enter name"),
        is_disabled=True,
    )


my_form_disabled = ui_form_disabled()
```

## Necessity Indicator

The `necessity_indicator` prop dictates whether form labels will use an icon or a label to outline which form fields are required. The default is “icon”.

```python
from deephaven import ui


@ui.component
def ui_form_indicator():
    def icon_indicator():
        return ui.form(
            ui.text_field(name="name", label="Name", is_required=True),
            ui.text_field(name="age", label="Age"),
            is_required=True,
        )

    def label_indicator():
        return ui.form(
            ui.text_field(name="name", label="Name", is_required=True),
            ui.text_field(name="age", label="Age"),
            is_required=True,
            necessity_indicator="label",
        )

    return [icon_indicator(), label_indicator()]


my_form_required = ui_form_indicator()
```

## Read only

The `is_read_only` prop makes form fields read-only to prevent user interaction. This is different than setting the `is_disabled` prop since the fields remains focusable, and the contents of the fields remain visible.

```python
from deephaven import ui


@ui.component
def ui_form_read_only():
    return ui.form(
        ui.text_field(name="name", label="Name"),
        is_read_only=True,
    )


my_form_read_only = ui_form_read_only()
```

## API Reference

Forms allow users to enter data that can be submitted while providing alignment and styling for form fields

**Returns:** `Element` The rendered form element.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "form", "parameters": [{"name": "*children", "type": "Any", "description": "The content to render within the container."}, {"name": "is_quiet", "type": "bool | None", "description": "Whether the form should be quiet.", "default": "None"}, {"name": "is_emphasized", "type": "bool | None", "description": "Whether the form should be emphasized.", "default": "None"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the form should be disabled.", "default": "None"}, {"name": "is_required", "type": "bool | None", "description": "Whether the form should be required.", "default": "None"}, {"name": "is_read_only", "type": "bool | None", "description": "Whether the form should be read only.", "default": "None"}, {"name": "validation_state", "type": "Literal['valid', 'invalid'] | None", "description": "Whether the Form elements should display their \"valid\" or \"invalid\" visual styling.", "default": "None"}, {"name": "validation_behavior", "type": "Literal['aria', 'native'] | None", "description": "Whether to use native HTML form validation to prevent form submission when a field value is missing or invalid, or mark fields as required or invalid via ARIA.", "default": "'aria'"}, {"name": "validation_errors", "type": "Dict[str, str | List[str]] | None", "description": "The validation errors for the form.", "default": "None"}, {"name": "action", "type": "str | None", "description": "The URL to submit the form data to.", "default": "None"}, {"name": "enc_type", "type": "Literal['application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain'] | None", "description": "The enctype attribute specifies how the form-data should be encoded when submitting it to the server.", "default": "None"}, {"name": "method", "type": "Literal['get', 'post', 'dialog'] | None", "description": "The HTTP method of the form.", "default": "None"}, {"name": "target", "type": "Literal['_self', '_blank', '_parent', '_top'] | None", "description": "The target attribute specifies a name or a keyword that indicates where to display the response that is received after submitting the form.", "default": "None"}, {"name": "auto_complete", "type": "Literal['on', 'off'] | None", "description": "Indicates whether input elements can by default have their values automatically completed by the browser.", "default": "None"}, {"name": "auto_capitalize", "type": "Literal['off', 'none', 'on', 'sentences', 'words', 'characters'] | None", "description": "Controls whether inputted text is automatically capitalized and, if so, in what manner.", "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": "on_submit", "type": "Callable[[dict[str, str]], None] | None", "description": "The function to call when the form is submitted.", "default": "None"}, {"name": "on_reset", "type": "Callable[[dict[str, str]], None] | None", "description": "The function to call when the form is reset.", "default": "None"}, {"name": "on_invalid", "type": "Callable[[dict[str, str]], None] | None", "description": "The function to call when the form is invalid.", "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": "overflow", "type": "str | None", "description": "Specifies what to do when the elment's content is too long to fit its size.", "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": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width of the element.", "default": "None"}, {"name": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height 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": "The position of the element.", "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": "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": "start", "type": "str | float | None", "description": "The distance from the start of the containing element, depending on layout direction.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element, depending on layout direction.", "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": "The unique identifier of 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"}]}} />