Form

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

Example

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()

Form Basic Example

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

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

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

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.

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”.

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.

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.

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.

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”.

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.

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.

ParametersTypeDefaultDescription
*childrenAnyThe content to render within the container.
is_quietbool |
None
NoneWhether the form should be quiet.
is_emphasizedbool |
None
NoneWhether the form should be emphasized.
is_disabledbool |
None
NoneWhether the form should be disabled.
is_requiredbool |
None
NoneWhether the form should be required.
is_read_onlybool |
None
NoneWhether the form should be read only.
validation_stateLiteral['valid', 'invalid'] |
None
NoneWhether the Form elements should display their "valid" or "invalid" visual styling.
validation_behaviorLiteral['aria', 'native'] |
None
'aria'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.
validation_errorsDict[str, str | List[str]] |
None
NoneThe validation errors for the form.
actionstr |
None
NoneThe URL to submit the form data to.
enc_typeLiteral['application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain'] |
None
NoneThe enctype attribute specifies how the form-data should be encoded when submitting it to the server.
methodLiteral['get', 'post', 'dialog'] |
None
NoneThe HTTP method of the form.
targetLiteral['_self', '_blank', '_parent', '_top'] |
None
NoneThe target attribute specifies a name or a keyword that indicates where to display the response that is received after submitting the form.
auto_completeLiteral['on', 'off'] |
None
NoneIndicates whether input elements can by default have their values automatically completed by the browser.
auto_capitalizeLiteral['off', 'none', 'on', 'sentences', 'words', 'characters'] |
None
NoneControls whether inputted text is automatically capitalized and, if so, in what manner.
label_positionLiteral['top', 'side']'top'The label's overall position relative to the element it is labeling.
label_alignLiteral['start', 'end'] |
None
NoneThe label's horizontal alignment relative to the element it is labeling.
necessity_indicatorLiteral['icon', 'label'] |
None
NoneWhether the required state should be shown as an icon or text.
keystr |
None
NoneA unique identifier used by React to render elements in a list.