# Number Field

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

## Example

```python
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,
)
```

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

```python
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.

```python
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.

```python
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.

```python
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.

```python
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat).

### Percentage

```python
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](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) currency codes. Examples include “USD” for the US dollar or “EUR” for the euro.

```python
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](https://unicode.org/reports/tr35/tr35-general.html#Unit_Elements). Examples include “degree”, “inch”, or “cup”.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "number_field", "parameters": [{"name": "is_quiet", "type": "bool | None", "description": "Whether the input should be displayed with a quiet style", "default": "None"}, {"name": "hide_stepper", "type": "bool | None", "description": "Whether to hide the increment and decrement stepper buttons", "default": "None"}, {"name": "decrement_aria_label", "type": "str | None", "description": "The aria label for the decrement stepper button. If not provided, the default is \"Decrement\"", "default": "None"}, {"name": "increment_aria_label", "type": "str | None", "description": "The aria label for the increment stepper button. If not provided, the default is \"Increment\"", "default": "None"}, {"name": "is_wheel_disabled", "type": "bool | None", "description": "Whether the input should change with scroll", "default": "None"}, {"name": "format_options", "type": "NumberFormatOptions | None", "description": "Options for formatting the displayed value, which also restricts input characters.", "default": "None"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the input should be disabled", "default": "None"}, {"name": "is_read_only", "type": "bool | None", "description": "Whether the input scan be selected but not changed by the user", "default": "None"}, {"name": "is_required", "type": "bool | None", "description": "Whether the input is required before form submission", "default": "None"}, {"name": "auto_focus", "type": "bool | None", "description": "Whether the input should be focused on page load", "default": "None"}, {"name": "value", "type": "float | None", "description": "The current value of the input", "default": "None"}, {"name": "default_value", "type": "float | None", "description": "The default value of the input", "default": "None"}, {"name": "min_value", "type": "float | None", "description": "The minimum value of the input", "default": "None"}, {"name": "max_value", "type": "float | None", "description": "The maximum value of the input", "default": "None"}, {"name": "step", "type": "float | None", "description": "The step value for the input", "default": "None"}, {"name": "label", "type": "Any | None", "description": "The label for the input", "default": "None"}, {"name": "description", "type": "Any | None", "description": "A description for the field. Provides a hint such as specific requirements for what to choose.", "default": "None"}, {"name": "error_message", "type": "Any | None", "description": "An error message to display when the field is invalid", "default": "None"}, {"name": "validation_state", "type": "Literal['valid', 'invalid'] | None", "description": "Whether the input should display its \"valid\" or \"invalid\" state", "default": "None"}, {"name": "name", "type": "str | None", "description": "The name of the input, used when submitting an HTML form", "default": "None"}, {"name": "label_position", "type": "Literal['top', 'side']", "description": "The position of the label relative to the input", "default": "'top'"}, {"name": "label_align", "type": "Literal['start', 'end'] | None", "description": "The alignment of the label relative to the input", "default": "None"}, {"name": "necessity_indicator", "type": "Literal['icon', 'label'] | None", "description": "Whether the required state should be shown as an icon or text", "default": "None"}, {"name": "contextual_help", "type": "Any | None", "description": "A ContentualHelp element to place next to the label", "default": "None"}, {"name": "on_focus", "type": "Callable[[FocusEvent], None] | None", "description": "Function called when the button receives focus.", "default": "None"}, {"name": "on_blur", "type": "Callable[[FocusEvent], None] | None", "description": "Function called when the button loses focus.", "default": "None"}, {"name": "on_focus_change", "type": "Callable[[bool], None] | None", "description": "Function called when the focus state changes.", "default": "None"}, {"name": "on_key_down", "type": "Callable[[KeyboardEvent], None] | None", "description": "Function called when a key is pressed.", "default": "None"}, {"name": "on_key_up", "type": "Callable[[KeyboardEvent], None] | None", "description": "Function called when a key is released.", "default": "None"}, {"name": "on_change", "type": "Callable[[float], None] | None", "description": "Function called when the input value changes", "default": "None"}, {"name": "flex", "type": "str | float | bool | None", "description": "When used in a flex layout, specifies how the element will grow or shrink to fit the space available.", "default": "None"}, {"name": "flex_grow", "type": "float | None", "description": "When used in a flex layout, specifies how the element will grow to fit the space available.", "default": "None"}, {"name": "flex_shrink", "type": "float | None", "description": "When used in a flex layout, specifies how the element will shrink to fit the space available.", "default": "None"}, {"name": "flex_basis", "type": "str | float | None", "description": "When used in a flex layout, specifies the initial main size of the element.", "default": "None"}, {"name": "align_self", "type": "Literal['auto', 'normal', 'start', 'end', 'center', 'flex-start', 'flex-end', 'self-start', 'self-end', 'stretch'] | None", "description": "Overrides the alignItems property of a flex or grid container.", "default": "None"}, {"name": "justify_self", "type": "Literal['auto', 'normal', 'start', 'end', 'flex-start', 'flex-end', 'self-start', 'self-end', 'center', 'left', 'right', 'stretch'] | None", "description": "Species how the element is justified inside a flex or grid container.", "default": "None"}, {"name": "order", "type": "int | None", "description": "The layout order for the element within a flex or grid container.", "default": "None"}, {"name": "grid_area", "type": "str | None", "description": "When used in a grid layout specifies, specifies the named grid area that the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "When used in a grid layout, specifies the row the element should be placed in within the grid.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "When used in a grid layout, specifies the column the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting row to span within the grid.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending row to span within the grid.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting column to span within the grid.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending column to span within the grid.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin for all four sides of the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin for the top side of the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin for the bottom side of the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin for the logical start side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin for the logical end side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin for the left and right sides of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin for the top and bottom sides of the element.", "default": "None"}, {"name": "width", "type": "str | float | None", "description": "The width of the element.", "default": "None"}, {"name": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width of the element.", "default": "None"}, {"name": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height of the element.", "default": "None"}, {"name": "max_height", "type": "str | float | None", "description": "The maximum height of the element.", "default": "None"}, {"name": "position", "type": "Literal['static', 'relative', 'absolute', 'fixed', 'sticky'] | None", "description": "The position of the element.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The distance from the top of the containing element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The distance from the bottom of the containing element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The distance from the left of the containing element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The distance from the right of the containing element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The distance from the start of the containing element, depending on layout direction.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element, depending on layout direction.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stack order of the element.", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Whether the element is hidden.", "default": "None"}, {"name": "id", "type": "str | None", "description": "The unique identifier of the element.", "default": "None"}, {"name": "aria_label", "type": "str | None", "description": "The label for the element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "The id of the element that labels the current element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "The id of the element that describes the current element.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "The id of the element that provides additional information about the current element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "A CSS class to apply to the element.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "A CSS style to apply to the element.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />