Text Field
Text fields are single-line text inputs, ideal for cases where users have a small amount of text to enter.
Example
from deephaven import ui
my_text_field_basic = ui.text_field(
label="Description", on_change=lambda value: print(f"Text changed to {value}")
)
UI Recommendations
Recommendations for creating text fields:
- Every text field should have a label specified. Without one, the text field is ambiguous. In the rare case that context is sufficient, the label is unnecessary; you must still include an aria-label via the
aria_labelprop. - Text field labels and help text should follow sentence casing.
- Use help text to provide instructions on input format, content, and requirements; the help text should not restate the same information as the label, or prompt a user to interact with the text field.
- Dynamically switch between help text and error messages based on input, ensuring both convey essential input requirements.
Use text_area for cases where multiline input is required.
Value
A text field’s value is empty by default, but the default_value prop can set an initial, uncontrolled value, or a controlled value can be set via the value prop.
from deephaven import ui
@ui.component
def ui_text_field_value_examples():
value, set_value = ui.use_state("Aardvark")
return [
ui.text_field(label="Favorite animal (Uncontrolled)", default_value="Aardvark"),
ui.text_field(
label="Favorite animal (controlled)", value=value, on_change=set_value
),
]
my_text_field_value_examples = ui_text_field_value_examples()
HTML Forms
Text fields can support a name prop for integration with HTML forms, allowing for easy identification of a value on form submission.
from deephaven import ui
my_text_field_name_example = ui.form(
ui.text_field(label="Email", name="email", type="email")
)
Labeling
To provide a visual label for the text field, use the label prop. To indicate that the text field is mandatory, use the is_required prop.
from deephaven import ui
@ui.component
def ui_text_field_is_required_examples():
return [
ui.text_field(label="Address"),
ui.text_field(label="Address", is_required=True),
]
my_text_field_is_required_example = ui_text_field_is_required_examples()
By setting is_required to True, the necessity_indicator is set to “icon” by default, but this can be changed. The necessity_indicator can also be used independently to indicate that the text field is optional.
When the necessity_indicator prop is set to “label”, a localized string will be generated for “(required)” or “(optional)” automatically.
from deephaven import ui
@ui.component
def ui_text_field_necessity_indicator_examples():
return [
ui.text_field(label="Address", is_required=True, necessity_indicator="label"),
ui.text_field(label="Address", necessity_indicator="label"),
]
my_text_field_necessity_indicator_examples = (
ui_text_field_necessity_indicator_examples()
)
Events
The on_change property is triggered whenever the value in the text field is edited.
from deephaven import ui
@ui.component
def ui_text_field_on_change_example():
value, set_value = ui.use_state("")
return [
ui.text_field(label="Your text", value=value, on_change=set_value),
ui.text(f"Text has been changed to: {value}"),
]
my_text_field_on_change_example = ui_text_field_on_change_example()
Input Types
The type prop changes the type of text field that is rendered to suit different input requirements.
from deephaven import ui
@ui.component
def ui_text_field_input_types_examples():
return ui.form(
ui.text_field(label="Name", type="text", is_required=True),
ui.text_field(label="Personal Website", type="url", is_required=True),
ui.text_field(label="Phone", type="tel", is_required=True),
ui.text_field(label="Email", type="email", is_required=True),
ui.text_field(label="Password", type="password", is_required=True),
ui.text_field(label="Search Bar", type="search"),
validation_behavior="native",
)
my_text_field_input_types_examples = ui_text_field_input_types_examples()
Quiet State
The is_quiet prop makes text fields “quiet”. This can be useful when the text area and its corresponding styling should not distract users from surrounding content.
from deephaven import ui
my_text_field_is_quiet_example = ui.text_field(label="Favorite animal", is_quiet=True)
Disabled State
The is_disabled prop disables text fields to prevent user interaction. This is useful when the text field should be visible but not available for input.
from deephaven import ui
my_text_field_is_disabled_example = ui.text_field(
label="Favorite animal", is_disabled=True
)
Read only
The is_read_only prop makes text fields read-only to prevent user interaction. This is different than setting the is_disabled prop since the text field remains focusable, and the contents of the text field remain visible.
from deephaven import ui
my_text_field_is_read_only_example = ui.text_field(
label="Favorite animal", default_value="Panda", is_read_only=True
)
Label position
By default, the position of a text field’s label is above the text field, but it can be changed to the side using the label_position prop.
While labels can be placed either on top or on the side of the text field, 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.
from deephaven import ui
@ui.component
def ui_text_field_label_position_examples():
return [
ui.text_field(label="Sample Label"),
ui.text_field(label="Sample Label", label_position="side", label_align="start"),
]
my_text_field_label_position_examples = ui_text_field_label_position_examples()
Help text
A text field can have both a description and an error_message. The description remains visible at all times, except when the validation_state is set to “invalid” and an error message is present. Use the error message to offer specific guidance on how to correct the input.
from deephaven import ui
@ui.component
def ui_text_field_help_text_examples():
return [
ui.text_field(
label="Comment",
default_value="Awesome!",
validation_state="valid",
description="Enter a comment.",
),
ui.text_field(
label="Comment",
validation_state="invalid",
error_message="Empty input is not allowed.",
),
]
my_text_field_help_text_examples = ui_text_field_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 text field.
from deephaven import ui
my_text_field_contextual_help_example = ui.text_field(
label="Favorite animal",
contextual_help=ui.contextual_help(
ui.heading("Information about animals"),
ui.content(
"Animals are classified into two main categories – the vertebrates and the invertebrates."
),
),
)
Custom width
The width prop adjusts the width of a text field, and the max_width prop enforces a maximum width.
from deephaven import ui
@ui.component
def ui_text_field_width_examples():
return [
ui.text_field(label="Favorite animal", width="size-3600"),
ui.text_field(label="Favorite animal", width="size-3600", max_width="100%"),
]
my_text_field_width_examples = ui_text_field_width_examples()
API Reference
TextFields are text inputs that allow users to input custom text entries with a keyboard. Various decorations can be displayed around the field to communicate the entry requirements.
Returns: Element The rendered text field element.
| Parameters | Type | Default | Description |
|---|---|---|---|
| icon | Element | None | UndefinedType | <deephaven.ui.types.types.UndefinedType object> | An icon to display at the start of the input |
| is_quiet | bool | None | None | Whether the input should be displayed with a quiet style |
| is_disabled | bool | None | None | Whether the input should be disabled |
| is_read_only | bool | None | None | Whether the input scan be selected but not changed by the user |
| is_required | bool | None | None | Whether the input is required before form submission |
| description | Any | None | None | A description for the field. Provides a hint such as specific requirements for what to choose. |
| error_message | Any | None | None | An error message to display when the field is invalid |
| auto_focus | bool | None | None | Whether the input should be focused on page load |
| value | str | None | None | The current value of the input |
| default_value | str | None | None | The default value of the input |
| label | Any | None | None | The label for the input |
| auto_complete | str | None | None | Describes the type of autocomplete functionality the input should provide |
| max_length | int | None | None | The maximum number of characters the input can accept |
| min_length | int | None | None | The minimum number of characters the input can accept |
| pattern | str | None | None | A regular expression that the input's value must match |
| type | Literal['text', 'search', 'url', 'tel', 'email', 'password'] | None | None | The type of input to display |
| input_mode | Literal['none', 'text', 'decimal', 'numeric', 'tel', 'search', 'email', 'url'] | None | None | Hints at the tpye of data that might be entered by the user while editing the element or its contents |
| name | str | None | None | The name of the input, used when submitting an HTML form |
| validation_state | Literal['valid', 'invalid'] | None | None | Whether the input should display its "valid" or "invalid" state |
| label_position | Literal['top', 'side'] | 'top' | The position of the label relative to the input |
| label_align | Literal['start', 'end'] | None | None | The alignment of the label relative to the input |
| necessity_indicator | Literal['icon', 'label'] | None | None | Whether the required state should be shown as an icon or text |
| contextual_help | Any | None | None | A ContentualHelp element to place next to the label |
| key | str | None | None | A unique identifier used by React to render elements in a list. |