Text Area

Text areas are multiline text inputs, ideal for cases where users have a sizable amount of text to enter. Text areas can be customized in the same ways that text fields can.

Example

from deephaven import ui

ta = ui.text_area(
    label="Description", on_change=lambda value: print(f"Text changed to {value}")
)

Text Area Basic Example

UI Recommendations

Recommendations for creating text areas:

  1. Text area should include a label, or else, the text area is ambiguous and not accessible.
  2. Text area labels and placeholder text should follow sentence casing.
  3. A text area should not use is_quiet styling if it has a fixed height, given that the field underline may be too far from the text to be considered part of the component.
  4. 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 area.
  5. Dynamically switch between help text and error messages based on input, ensuring both convey essential input requirements.

Consider using text_field for cases where concise, single-line input is required.

Value

A text area’s value is empty by default, but an initial, uncontrolled, value can be set using the default_value prop, or, a controlled value can be set via the value prop.

from deephaven import ui


@ui.component
def text_area_value_prop():
    return [
        ui.text_area(label="Sample (Uncontrolled)", default_value="Value 1"),
        ui.text_area(label="Sample (controlled)", value="Value 2"),
    ]


text_area_value_example = text_area_value_prop()

Labeling

To provide a visual label for the text area, use the label prop. To indicate that the text area is mandatory, use the is_required prop.

from deephaven import ui


@ui.component
def text_area_is_required_prop():
    return [
        ui.text_area(label="Address"),
        ui.text_area(label="Address", is_required=True),
    ]


text_area_is_required_example = text_area_is_required_prop()

By setting is_required to True, the necessity_indicator is set to “icon” by default, but this can be changed. Also, the necessity_indicator can be used indepdendently to indicate that the text area 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 text_area_necessity_indicator_prop():
    return [
        ui.text_area(label="Address", is_required=True, necessity_indicator="label"),
        ui.text_area(label="Address", necessity_indicator="label"),
    ]


text_area_necessity_indicator_example = text_area_necessity_indicator_prop()

Events

The on_change property is triggered whenever the value in the text area is edited.

from deephaven import ui


@ui.component
def text_area_on_change_prop():
    value, set_value = ui.use_state("")
    return ui.text_area(label="Your text", value=value, on_change=set_value)


text_area_on_change_example = text_area_on_change_prop()

HTML Forms

Text areas can support a name prop for integration with HTML forms, allowing for easy identification of a value on form submission.

from deephaven import ui


text_area_name_example = ui.form(ui.flex(ui.text_area(label="Comment", name="comment")))

Quiet State

The is_quiet prop makes text areas “quiet”. This can be useful when the text area and its corresponding styling should not distract users from surrounding content.

from deephaven import ui


text_area_is_quiet_example = ui.text_area(label="Sample", is_quiet=True)

Disabled State

The is_disabled prop disables text areas to prevent user interaction. This is useful when the text area should be visible but not available for input.

from deephaven import ui


text_area_is_disabled_example = ui.text_area(label="Sample", is_disabled=True)

Read only

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

from deephaven import ui


text_area_is_read_only_example = ui.text_area(label="Sample", is_read_only=True)

Label position

By default, the position of a text area’s label is above the text area, 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 area, 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 text_area_label_position_props():
    return [
        ui.text_area(label="Test Label"),
        ui.text_area(label="Test Label", label_position="side", label_align="start"),
    ]


text_area_label_position_example = text_area_label_position_props()

Help text

A text area 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 text_area_help_text_props():
    return [
        ui.text_area(
            label="Comment",
            default_value="Awesome!",
            validation_state="valid",
            description="Enter a comment.",
        ),
        ui.text_area(
            label="Comment",
            validation_state="invalid",
            error_message="Empty input is not allowed.",
        ),
    ]


text_area_help_text_example = text_area_help_text_props()

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

from deephaven import ui


text_area_contextual_help_example = ui.text_area(
    label="Comment", contextual_help=ui.contextual_help(ui.heading("Sample tips"))
)

Custom width

The width prop adjusts the width of a text area, and the max_width prop enforces a maximum width.

from deephaven import ui


@ui.component
def text_area_width_props():
    return [
        ui.text_area(label="Sample Label", width="size-3600"),
        ui.text_area(label="Sample Label", width="size-3600", max_width="100%"),
    ]


text_area_width_example = text_area_width_props()

API Reference

TextAreas are multiline text inputs, useful for cases where users have a sizable amount of text to enter. They allow for all customizations that are available to text fields.

Returns: Element The element representing the text area

ParametersTypeDefaultDescription
iconElement |
Literal['account', 'activate_breakpoints', 'add', 'archive', 'arrow_both', 'arrow_circle_down', 'arrow_circle_left', 'arrow_circle_right', 'arrow_circle_up', 'arrow_down', 'arrow_left', 'arrow_right', 'arrow_small_down', 'arrow_small_left', 'arrow_small_right', 'arrow_small_up', 'arrow_swap', 'arrow_up', 'azure_devops', 'azure', 'beaker_stop', 'beaker', 'bell_dot', 'bell_slash_dot', 'bell_slash', 'bell', 'blank', 'bold', 'book', 'bookmark', 'bracket_dot', 'bracket_error', 'briefcase', 'broadcast', 'browser', 'bug', 'calendar', 'call_incoming', 'call_outgoing', 'case_sensitive', 'check_all', 'check', 'checklist', 'chevron_down', 'chevron_left', 'chevron_right', 'chevron_up', 'chip', 'chrome_close', 'chrome_maximize', 'chrome_minimize', 'chrome_restore', 'circle_filled', 'circle_large_filled', 'circle_large', 'circle_slash', 'circle_small_filled', 'circle_small', 'circle', 'circuit_board', 'clear_all', 'clippy', 'close_all', 'close', 'cloud_download', 'cloud_upload', 'cloud', 'code_oss', 'code', 'coffee', 'collapse_all', 'color_mode', 'combine', 'comment_discussion', 'comment_draft', 'comment_unresolved', 'comment', 'compass_active', 'compass_dot', 'compass', 'copilot', 'copy', 'coverage', 'credit_card', 'dash', 'dashboard', 'database', 'debug_all', 'debug_alt_small', 'debug_alt', 'debug_breakpoint_conditional_unverified', 'debug_breakpoint_conditional', 'debug_breakpoint_data_unverified', 'debug_breakpoint_data', 'debug_breakpoint_function_unverified', 'debug_breakpoint_function', 'debug_breakpoint_log_unverified', 'debug_breakpoint_log', 'debug_breakpoint_unsupported', 'debug_console', 'debug_continue_small', 'debug_continue', 'debug_coverage', 'debug_disconnect', 'debug_line_by_line', 'debug_pause', 'debug_rerun', 'debug_restart_frame', 'debug_restart', 'debug_reverse_continue', 'debug_stackframe_active', 'debug_stackframe', 'debug_start', 'debug_step_back', 'debug_step_into', 'debug_step_out', 'debug_step_over', 'debug_stop', 'debug', 'desktop_download', 'device_camera_video', 'device_camera', 'device_mobile', 'diff_added', 'diff_ignored', 'diff_modified', 'diff_multiple', 'diff_removed', 'diff_renamed', 'diff_single', 'diff', 'discard', 'edit', 'editor_layout', 'ellipsis', 'empty_window', 'error_small', 'error', 'exclude', 'expand_all', 'export', 'extensions', 'eye_closed', 'eye', 'feedback', 'file_binary', 'file_code', 'file_media', 'file_pdf', 'file_submodule', 'file_symlink_directory', 'file_symlink_file', 'file_zip', 'file', 'files', 'filter_filled', 'filter', 'flame', 'fold_down', 'fold_up', 'fold', 'folder_active', 'folder_library', 'folder_opened', 'folder', 'game', 'gear', 'gift', 'gist_secret', 'gist', 'git_commit', 'git_compare', 'git_fetch', 'git_merge', 'git_pull_request_closed', 'git_pull_request_create', 'git_pull_request_draft', 'git_pull_request_go_to_changes', 'git_pull_request_new_changes', 'git_pull_request', 'git_stash_apply', 'git_stash_pop', 'git_stash', 'github_action', 'github_alt', 'github_inverted', 'github_project', 'github', 'globe', 'go_to_file', 'go_to_search', 'grabber', 'graph_left', 'graph_line', 'graph_scatter', 'graph', 'gripper', 'group_by_ref_type', 'heart_filled', 'heart', 'history', 'home', 'horizontal_rule', 'hubot', 'inbox', 'indent', 'info', 'insert', 'inspect', 'issue_draft', 'issue_reopened', 'issues', 'italic', 'jersey', 'json', 'kebab_vertical', 'key', 'law', 'layers_active', 'layers_dot', 'layers', 'layout_activitybar_left', 'layout_activitybar_right', 'layout_centered', 'layout_menubar', 'layout_panel_center', 'layout_panel_justify', 'layout_panel_left', 'layout_panel_off', 'layout_panel_right', 'layout_panel', 'layout_sidebar_left_off', 'layout_sidebar_left', 'layout_sidebar_right_off', 'layout_sidebar_right', 'layout_statusbar', 'layout', 'library', 'lightbulb_autofix', 'lightbulb_sparkle', 'lightbulb', 'link_external', 'link', 'list_filter', 'list_flat', 'list_ordered', 'list_selection', 'list_tree', 'list_unordered', 'live_share', 'loading', 'location', 'lock_small', 'lock', 'magnet', 'mail_read', 'mail', 'map_filled', 'map_vertical_filled', 'map_vertical', 'map', 'markdown', 'megaphone', 'mention', 'menu', 'merge', 'mic_filled', 'mic', 'milestone', 'mirror', 'mortar_board', 'move', 'multiple_windows', 'music', 'mute', 'new_file', 'new_folder', 'newline', 'no_newline', 'note', 'notebook_template', 'notebook', 'octoface', 'open_preview', 'organization', 'output', 'package', 'paintcan', 'pass_filled', 'pass', 'percentage', 'person_add', 'person', 'piano', 'pie_chart', 'pin', 'pinned_dirty', 'pinned', 'play_circle', 'play', 'plug', 'preserve_case', 'preview', 'primitive_square', 'project', 'pulse', 'question', 'quote', 'radio_tower', 'reactions', 'record_keys', 'record_small', 'record', 'redo', 'references', 'refresh', 'regex', 'remote_explorer', 'remote', 'remove', 'replace_all', 'replace', 'reply', 'repo_clone', 'repo_force_push', 'repo_forked', 'repo_pull', 'repo_push', 'repo', 'report', 'request_changes', 'robot', 'rocket', 'root_folder_opened', 'root_folder', 'rss', 'ruby', 'run_above', 'run_all_coverage', 'run_all', 'run_below', 'run_coverage', 'run_errors', 'save_all', 'save_as', 'save', 'screen_full', 'screen_normal', 'search_fuzzy', 'search_stop', 'search', 'send', 'server_environment', 'server_process', 'server', 'settings_gear', 'settings', 'share', 'shield', 'sign_in', 'sign_out', 'smiley', 'snake', 'sort_precedence', 'source_control', 'sparkle_filled', 'sparkle', 'split_horizontal', 'split_vertical', 'squirrel', 'star_empty', 'star_full', 'star_half', 'stop_circle', 'surround_with', 'symbol_array', 'symbol_boolean', 'symbol_class', 'symbol_color', 'symbol_constant', 'symbol_enum_member', 'symbol_enum', 'symbol_event', 'symbol_field', 'symbol_file', 'symbol_interface', 'symbol_key', 'symbol_keyword', 'symbol_method', 'symbol_misc', 'symbol_namespace', 'symbol_numeric', 'symbol_operator', 'symbol_parameter', 'symbol_property', 'symbol_ruler', 'symbol_snippet', 'symbol_string', 'symbol_structure', 'symbol_variable', 'sync_ignored', 'sync', 'table', 'tag', 'target', 'tasklist', 'telescope', 'terminal_bash', 'terminal_cmd', 'terminal_debian', 'terminal_linux', 'terminal_powershell', 'terminal_tmux', 'terminal_ubuntu', 'terminal', 'text_size', 'three_bars', 'thumbsdown_filled', 'thumbsdown', 'thumbsup_filled', 'thumbsup', 'tools', 'trash', 'triangle_down', 'triangle_left', 'triangle_right', 'triangle_up', 'twitter', 'type_hierarchy_sub', 'type_hierarchy_super', 'type_hierarchy', 'unfold', 'ungroup_by_ref_type', 'unlock', 'unmute', 'unverified', 'variable_group', 'verified_filled', 'verified', 'versions', 'vm_active', 'vm_connect', 'vm_outline', 'vm_running', 'vm', 'vr', 'vscode_insiders', 'vscode', 'wand', 'warning', 'watch', 'whitespace', 'whole_word', 'window', 'word_wrap', 'workspace_trusted', 'workspace_unknown', 'workspace_untrusted', 'zoom_in', 'zoom_out', 'dh_add_small', 'dh_arrow_to_bottom', 'dh_arrow_to_top', 'dh_check_square', 'dh_chevron_down_square', 'dh_circle_large_outline_notch', 'dh_clock', 'dh_exclamation', 'dh_eye_slash', 'dh_eye', 'dh_file_certificate', 'dh_file_csv', 'dh_file_download', 'dh_file_print', 'dh_file_search', 'dh_file_spreadsheet', 'dh_filter_filled', 'dh_filter_slash', 'dh_freeze', 'dh_gear_filled', 'dh_gears_filled', 'dh_graph_line_down', 'dh_graph_line_up', 'dh_i_cursor', 'dh_input', 'dh_new_circle_large_filled', 'dh_new_square_filled', 'dh_organization_add', 'dh_pandas', 'dh_panels', 'dh_python', 'dh_refresh', 'dh_remove_square_filled', 'dh_run_selection', 'dh_shapes', 'dh_share_filled', 'dh_share', 'dh_sort_alpha_down', 'dh_sort_alpha_up', 'dh_sort_amount_down', 'dh_sort_down', 'dh_sort_slash', 'dh_sort_up', 'dh_sort', 'dh_split_both', 'dh_square_filled', 'dh_sticky_note_filled', 'dh_strikethrough', 'dh_table', 'dh_trash_undo', 'dh_triangle_down_square', 'dh_truck', 'dh_underline', 'dh_unlink', 'dh_user_incognito', 'dh_user', 'dh_warning_circle_filled', 'dh_warning_filled'] |
None |
UndefinedType
<deephaven.ui.types.types.UndefinedType object>An icon to display at the start of the input
is_quietbool |
None
NoneWhether the input should be displayed with a quiet style
is_disabledbool |
None
NoneWhether the input should be disabled
is_read_onlybool |
None
NoneWhether the input scan be selected but not changed by the user
is_requiredbool |
None
NoneWhether the input is required before form submission
descriptionAny |
None
NoneA description for the area. Provides a hint such as specific requirements for what to choose.
error_messageAny |
None
NoneAn error message to display when the area is invalid
auto_focusbool |
None
NoneWhether the input should be focused on page load
valuestr |
None
NoneThe current value of the input
default_valuestr |
None
NoneThe default value of the input
labelAny |
None
NoneThe label for the input
auto_completestr |
None
NoneDescribes the type of autocomplete functionality the input should provide
max_lengthint |
None
NoneThe maximum number of characters the input can accept
min_lengthint |
None
NoneThe minimum number of characters the input can accept
input_modeLiteral['none', 'text', 'decimal', 'numeric', 'tel', 'search', 'email', 'url'] |
None
NoneHints at the tpye of data that might be entered by the user while editing the element or its contents
namestr |
None
NoneThe name of the input, used when submitting an HTML form
validation_stateLiteral['valid', 'invalid'] |
None
NoneWhether the input should display its "valid" or "invalid" state
label_positionLiteral['top', 'side']'top'The position of the label relative to the input
label_alignLiteral['start', 'end'] |
None
NoneThe alignment of the label relative to the input
necessity_indicatorLiteral['icon', 'label'] |
None
NoneWhether the required state should be shown as an icon or text
contextual_helpAny |
None
NoneA ContentualHelp element to place next to the label
keystr |
None
NoneA unique identifier used by React to render elements in a list.