Number Field

Number fields allow users to enter a number and increase or decrease the value using stepper buttons.

Example

from deephaven import ui


my_number_field = ui.number_field(
    label="Width",
    on_change=lambda value: print(f"Number changed to {value}"),
    default_value=1024,
)

Number Field Basic Example

Value

A number field’s value is empty by default. The default_value prop can set an initial, uncontrolled value, or the value prop can set a controlled value.

from deephaven import ui


@ui.component
def ui_number_field_value_examples():
    value, set_value = ui.use_state(5)
    return [
        ui.number_field(label="Hours (Uncontrolled)", default_value=5),
        ui.number_field(
            label="Favorite animal (controlled)", value=value, on_change=set_value
        ),
    ]


my_number_field_value_examples = ui_number_field_value_examples()

HTML Forms

Number 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_number_field_name_example = ui.form(
    ui.number_field(
        label="Withdrawal amount",
        name="amount",
        default_value=45,
        format_options={"currency_sign": "standard"},
    )
)

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_number_field_is_required_examples():
    return [
        ui.number_field(label="Birth year"),
        ui.number_field(label="Birth year", is_required=True),
    ]


my_number_field_is_required_example = ui_number_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_number_field_necessity_indicator_examples():
    return [
        ui.number_field(
            label="Birth year", is_required=True, necessity_indicator="label"
        ),
        ui.number_field(label="Birth year", necessity_indicator="label"),
    ]


my_number_field_necessity_indicator_examples = (
    ui_number_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_number_field_on_change_example():
    value, set_value = ui.use_state("")
    return [
        ui.number_field(label="Your age", value=value, on_change=set_value),
        ui.text(f"Age has been changed to: {value}"),
    ]


my_number_field_on_change_example = ui_number_field_on_change_example()

Format Options

The format_options prop dictates how the value is displayed and which characters can be inputted. There are 3 styles supported by this parameter: Percentage, Currency, and Units.

Note: This prop is compatible with the option parameter of Intl.NumberFormat.

Percentage

from deephaven import ui


@ui.component
def ui_number_field_percentage_example():

    return [
        ui.number_field(
            label="Percent", default_value="0.5", format_options={"style": "percent"}
        ),
    ]


my_number_field_percentage_example = ui_number_field_percentage_example()

Currency

When the style is set to currency, a specific currency must be defined through the currency prop. Possible values follow the ISO 4217 currency codes. Examples include “USD” for the US dollar or “EUR” for the euro.

from deephaven import ui


@ui.component
def ui_number_field_currency_example():

    return [
        ui.number_field(
            label="Currency",
            default_value="49.99",
            format_options={"style": "currency", "currency": "USD"},
        ),
    ]


my_number_field_currency_example = ui_number_field_currency_example()

Units

When the style is set to unit, a specific unit must be defined through the unit prop. Possible values are defined in UTS #35, Part 2 Section 6. Examples include “degree”, “inch”, or “cup”.

from deephaven import ui


@ui.component
def ui_number_field_unit_example():

    return [
        ui.number_field(
            label="Unit",
            default_value="10",
            format_options={"style": "unit", "unit": "inch"},
        ),
    ]


my_number_field_unit_example = ui_number_field_unit_example()

Quiet State

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

from deephaven import ui


my_number_field_is_quiet_example = ui.number_field(label="Age", is_quiet=True)

Disabled State

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

from deephaven import ui


my_number_field_is_disabled_example = ui.number_field(label="Age", is_disabled=True)

Read only

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

from deephaven import ui


my_number_field_is_read_only_example = ui.number_field(
    label="Age", default_value=25, is_read_only=True
)

Label position

By default, the position of a number field’s label is above the number 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 number 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_number_field_label_position_examples():
    return [
        ui.number_field(label="Sample Label"),
        ui.number_field(
            label="Sample Label", label_position="side", label_align="start"
        ),
    ]


my_number_field_label_position_examples = ui_number_field_label_position_examples()

Help text

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


my_number_field_help_number_examples = ui_number_field_help_number_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 number field.

from deephaven import ui


my_number_field_contextual_help_example = ui.number_field(
    label="FPS",
    contextual_help=ui.contextual_help(
        ui.heading("What is FPS"),
        ui.content(
            "Frames Per Second (FPS) is a measure of how many individual frames (images) are displayed in one second of video or animation"
        ),
    ),
)

Custom width

The width prop adjusts the width of a number field, and the max_width prop enforces a maximum width.

from deephaven import ui


@ui.component
def ui_number_field_width_examples():
    return [
        ui.number_field(label="Birth year", width="size-3600"),
        ui.number_field(label="Birth year", width="size-3600", max_width="100%"),
    ]


my_number_field_width_examples = ui_number_field_width_examples()

API Reference

NumberFields allow users to enter a number, and increment or decrement the value using stepper buttons.

Returns: Element The rendered number field element.

ParametersTypeDefaultDescription
is_quietbool |
None
NoneWhether the input should be displayed with a quiet style
hide_stepperbool |
None
NoneWhether to hide the increment and decrement stepper buttons
decrement_aria_labelstr |
None
NoneThe aria label for the decrement stepper button. If not provided, the default is "Decrement"
increment_aria_labelstr |
None
NoneThe aria label for the increment stepper button. If not provided, the default is "Increment"
is_wheel_disabledbool |
None
NoneWhether the input should change with scroll
format_optionsNumberFormatOptions |
None
NoneOptions for formatting the displayed value, which also restricts input characters.
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
auto_focusbool |
None
NoneWhether the input should be focused on page load
valuefloat |
None
NoneThe current value of the input
default_valuefloat |
None
NoneThe default value of the input
min_valuefloat |
None
NoneThe minimum value of the input
max_valuefloat |
None
NoneThe maximum value of the input
stepfloat |
None
NoneThe step value for the input
labelAny |
None
NoneThe label for the input
descriptionAny |
None
NoneA description for the field. Provides a hint such as specific requirements for what to choose.
error_messageAny |
None
NoneAn error message to display when the field is invalid
validation_stateLiteral['valid', 'invalid'] |
None
NoneWhether the input should display its "valid" or "invalid" state
namestr |
None
NoneThe name of the input, used when submitting an HTML form
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.