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()
Events
Forms can handle three events:
- Submit: Triggered when the form is submitted. Users can define a callback function to handle the form data upon submission.
- Reset: Triggered when the form is reset. This event can be used to clear the form fields or reset them to their initial values.
- 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.
| Parameters | Type | Default | Description |
|---|---|---|---|
| *children | Any | The content to render within the container. | |
| is_quiet | bool | None | None | Whether the form should be quiet. |
| is_emphasized | bool | None | None | Whether the form should be emphasized. |
| is_disabled | bool | None | None | Whether the form should be disabled. |
| is_required | bool | None | None | Whether the form should be required. |
| is_read_only | bool | None | None | Whether the form should be read only. |
| validation_state | Literal['valid', 'invalid'] | None | None | Whether the Form elements should display their "valid" or "invalid" visual styling. |
| validation_behavior | Literal['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_errors | Dict[str, str | List[str]] | None | None | The validation errors for the form. |
| action | str | None | None | The URL to submit the form data to. |
| enc_type | Literal['application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain'] | None | None | The enctype attribute specifies how the form-data should be encoded when submitting it to the server. |
| method | Literal['get', 'post', 'dialog'] | None | None | The HTTP method of the form. |
| target | Literal['_self', '_blank', '_parent', '_top'] | None | None | The target attribute specifies a name or a keyword that indicates where to display the response that is received after submitting the form. |
| auto_complete | Literal['on', 'off'] | None | None | Indicates whether input elements can by default have their values automatically completed by the browser. |
| auto_capitalize | Literal['off', 'none', 'on', 'sentences', 'words', 'characters'] | None | None | Controls whether inputted text is automatically capitalized and, if so, in what manner. |
| label_position | Literal['top', 'side'] | 'top' | The label's overall position relative to the element it is labeling. |
| label_align | Literal['start', 'end'] | None | None | The label's horizontal alignment relative to the element it is labeling. |
| necessity_indicator | Literal['icon', 'label'] | None | None | Whether the required state should be shown as an icon or text. |
| key | str | None | None | A unique identifier used by React to render elements in a list. |