Number Input

Anatomy

1. Label: Title of the Number Input.
2. Input Container: Rectangular container that houses placeholder and input text.
3. Placeholder/Input Text: Placeholder text is optional and shows an example of how to format the text for the input required.
4. Percent Symbol: (Optional) Only used to provide context around the intent of the input. These elements are not editable by the user.

Usage Guidance

When to Use

• When numeric data needs to be entered, such as: quantities, counts, zip codes, percentages, decimals, etc.

When to Consider Something Else

• Use a Text Input when the intended user input is all or partially text based.
• Use a Text Area when you need to let users enter an amount of text that’s longer than a single line.
• Use a Rich Text Editor if styling is needed, such as for configuring email messages.
• Consider using a Prompt, Radio or Checkboxes if there is predetermined data that a user should not input themselves
• When entering phone numbers use the dedicated Phone Number input, which provides additional controls and formatting specific to this type of data.
• Monetary data should use the Currency Input, which provides additional controls and formatting specific to this type of data.
• Date Inputs/pickers should be used for all date based data. These inputs are built for easier data entry and come with specific date formatting.
• Time Inputs/pickers should be used for all time based data. These inputs are built for easier data entry and come with specific time based formatting.
• For more information about different types of inputs, review the Form pattern.

Behaviors

Number Inputs follow all the same interaction and notifications state as our Text Input.

Keyboards

Mobile devices utilize on-screen keyboards. Typically it is up to the designer to specify the keyboard-type in their designs, however the number input will always default to the native number pad.

Screen Size Differences

Typically, inputs on mobile should stretch to the full width of the screen. However, there are some exceptions when providing smaller inputs to better set expectations for the input, such as providing a smaller input for entering a ZIP code. For larger mobile devices, inputs should have a maximum width of 600 pts to retain proper readability.

Examples

Number

The standard number input for most all numeric data. This supports decimals, and positive/negative numbers.

Percentage

The percentage variant appends a percent symbol (%) to the trailing end of the number string to provide additional meaning and context to the user. This also supports decimals, and positive/negative numbers.

API Guidelines

Methods

Class name: LabelledNumberInput Module name: UIComponentsPlugin

    public init(
        featureData: FeatureMetricsData,
        input: Binding<String>,
        unformattedOutput: Binding<String>,
        allowNegative: Bool,
        allowDecimal: Bool,
        maxIntegerDigits: Int,
        maxFractionDigits: Int,
        isPercentageInput: Bool,
        label: String,
        helperText: String?,
        context: Binding<SemanticContext>,
        locale: Locale,
        localizer: LocalizationAdapting,
        onFocusChanged: ((Bool) -> Void)? = nil,
        onSubmission: (() -> Void)? = nil
    )

Parameters

Accessibility Guidelines

• Coming soon…

Content Guidelines

• Labels for Number Inputs are written in title case.
• Use helper text to instruct the user what the proper input may be.
• Use placeholder text only to provide examples of proper inputs. Never use placeholder text to help instruct users.
• For additional numeric content guidance review the Numbers section.

Anatomy

1. Label: Title of the Number Input.
2. Input Container: Rectangular container that houses placeholder and input text.
3. Placeholder/Input Text: Placeholder text is optional and shows an example of how to format the text for the input required.
4. Percent Symbol: (Optional) Only used to provide context around the intent of the input. These elements are not editable by the user.

Usage Guidance

When to Use

• When numeric data needs to be entered, such as: quantities, counts, zip codes, percentages, decimals, etc.

When to Consider Something Else

• Use a Text Input when the intended user input is all or partially text based.
• Use a Text Area when you need to let users enter an amount of text that’s longer than a single line.
• Use a Rich Text Editor if styling is needed, such as for configuring email messages.
• Consider using a Prompt, Radio or Checkboxes if there is predetermined data that a user should not input themselves
• When entering phone numbers use the dedicated Phone Number input, which provides additional controls and formatting specific to this type of data.
• Monetary data should use the Currency Input, which provides additional controls and formatting specific to this type of data.
• Date Inputs/pickers should be used for all date based data. These inputs are built for easier data entry and come with specific date formatting.
• Time Inputs/pickers should be used for all time based data. These inputs are built for easier data entry and come with specific time based formatting.
• For more information about different types of inputs, review the Form pattern.

Behaviors

Number Inputs follow all the same interaction and notifications state as our Text Input.

Keyboards

Mobile devices utilize on-screen keyboards. Typically it is up to the designer to specify the keyboard-type in their designs, however the number input will always default to the native number pad.

Screen Size Differences

Typically, inputs on mobile should stretch to the full width of the screen. However, there are some exceptions when providing smaller inputs to better set expectations for the input, such as providing a smaller input for entering a ZIP code. For larger mobile devices, inputs should have a maximum width of 600 pts to retain proper readability.

Examples

Number

The standard number input for most all numeric data. This supports decimals, and positive/negative numbers.

Percentage

The percentage variant appends a percent symbol (%) to the trailing end of the number string to provide additional meaning and context to the user. This also supports decimals, and positive/negative numbers.

API Guidelines

Methods

  fun NumberInputUiComponent(
    modifier: Modifier = Modifier,
    label: String? = null,
    value: String = "",
    onValueChange: (String) -> Unit,
    onClickClearTextIcon: (() -> Unit) = {},
    placeholder: String? = null,
    helperText: String? = null,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    isDecimal: Boolean = true,
    isPercent: Boolean = false,
    allowNegative: Boolean = true,
    maximumIntegerDigits: Int = 100,
    maximumDecimalDigits: Int = 100,
    semanticState: SemanticState = SemanticState()
)

Parameters

Accessibility Guidelines

• Coming soon…

Content Guidelines

• Labels for Number Inputs are written in title case.
• Use helper text to instruct the user what the proper input may be.
• Use placeholder text only to provide examples of proper inputs. Never use placeholder text to help instruct users.
• For additional numeric content guidance review the Numbers section.