Phone Number Input
Phone Number Input allows users to enter phone numbers and selection of country codes.
Anatomy
Similar to Currency Input, Phone Number Input is a combo of a Prompt and a Number Input.
- Label: Title or brief description of input.
- Pill: Displays the flag of the country or geographical region most closely associated with the phone number country code and opens the Bottom Sheet upon interaction.
- Input Placeholder and Text: Displays and automatically formats the entered phone number. Placeholder text is optional.
- Contextual Message: (Optional) Helper text used to aid in the understanding of an acceptable input. (Conditional) Appears if the warning or error state is triggered, in which case the helper text would be replaced by the Error/Warning message when triggered.
- Input Field: Contains the Pill, country code, and input phone number.
- Extension Field: Contains the input phone number extension number.
- Bottom Sheet: Opens when the pill has been tapped. Allows for selection of phone number country code.
- Search Input: Used to search for country codes.
- Expandable: Used as a section header to separate different groups of content.
- List: Displays flag, country name and country code.
Usage Guidance
When to Use
- Use Phone Number Input for collecting a phone number.
When to Consider Something Else
- Use a Number Input if the numerical data is not associated with a phone number.
- Use a prompt if you need to select a country by itself outside of the context of a phone number.
- A Phone Number Input should not be used for dialing a phone number.
Behaviors
Selecting a Country Code
Tapping the pill in the Phone Number Input invokes our Bottom Sheet, which follows the typical patterns found in our Prompts. Country codes are defaulted based on the user’s provided phone number. Once in the Prompt/Bottom Sheet, a user can either cancel their decision (closing the bottom sheet), select a new country code, or search for a country code. Country codes are first listed by Frequently Used, then by country in alphabetical order. Upon selection of a new currency, users should be redirected back to their preceding screen with their new selection. Please note that the location of the input on the screen should remain the same to prevent a disorienting experience.
Frequently Used
When opening the bottom sheet, countries are automatically sorted into two groups, frequently used and all countries. The frequently used section is pre-determined based on Workday’s global usage data. The all countries section is displayed alphabetically by default.
Searching for a Country Code
Country codes are alphabetically or numerically searchable by either their country/geographical region of origin, or the country code itself.
Inputtable Country Codes
The country code is automatically populated within the input field based on the selected pill. However, the country code may also be manually input/adjusted via numberpad by deleting the numerical code and entering a new one.
Inputting a Value
When selecting the input field instead of the pill, the Phone Number Input should enter its active state, where the numberpad simultaneously comes into view.
Phone Number Formatting
As phone numbers are entered they are automatically formatted based on the selected country code. Users do not need to enter any additional characters beyond numbers, such as parentheses for area codes or dashes between sections.
Variations
With Extension
This variation includes an extra input field at the end for phone number extensions. If the screen size is too small to accommodate both fields in one line then the extension field is placed below the phone number field stretching to 50% of the column width.
Without Extension
If product or design has determined that the extension is not needed for their use case, the extension field can be hidden.
Content Guidelines
When writing content for Phone Number Input, please refer to the placeholder and instructional text sections of Content’s UI Text recommendations.
API Guidelines
Methods
Class name: PhoneNumberInput Module name: UIComponentsPlugin
public init(
inputLabel: String,
phoneInput: Binding<String>,
unformattedOutput: Binding<String>,
extensionInput: Binding<String>? = nil,
isRequired: Bool = false,
phoneInputAppearance: BaseLabeledInputAppearance,
extensionInputAppearance: BaseLabeledInputAppearance? = nil,
helperText: LabeledInputHelperText? = nil,
locale: Locale,
localizer: LocalizationAdapting,
featureData: FeatureMetricsData
)Parameters
| Name | Description |
|---|---|
| inputLabel | The title placed above the input field. |
| phoneInput | Binding to the formatted phone number string. May contain + (plus sign), 0-9, (space), - (dash), and () (parentheses) |
| unformattedOutput | Binding to the phone number string without formatting. May contain + and 0-9. |
| extensionInput | Numbers-only string for the phone extension. |
| isRequired | Adds a red asterisk to the input label if true. |
| phoneInputAppearance | Normal, warning, or error appearance of the phone number input field. |
| extensionInputAppearance | Normal, warning, or error appearance of the extension input field. |
| helperText | Text to display below the input field. Can have normal, warning, or error appearance. |
| locale | Used to initialize the phone number processor, provide initial/default country code, and localize names from ISO codes. |
| localizer | Localizer for the component, especially for localizing UI strings. |
| featureData | The feature name/context and the screen ID in which the component appears. |
Accessibility Guidelines
- Coming soon…
Anatomy
Similar to Currency Input, Phone Number Input is a combo of a Prompt and a Number Input.
- Label: Title or brief description of input.
- Pill: Displays the flag of the country or geographical region most closely associated with the phone number country code and opens the Bottom Sheet upon interaction.
- Input Placeholder and Text: Displays and automatically formats the entered phone number. Placeholder text is optional.
- Contextual Message: (Optional) Helper text used to aid in the understanding of an acceptable input. (Conditional) Appears if the warning or error state is triggered, in which case the helper text would be replaced by the Error/Warning message when triggered.
- Input Field: Contains the Pill, country code, and input phone number.
- Extension Field: Contains the input phone number extension number.
- Bottom Sheet: Opens when the pill has been tapped. Allows for selection of phone number country code.
- Search Input: Used to search for country codes.
- Expandable: Used as a section header to separate different groups of content.
- List: Displays flag, country name and country code.
Usage Guidance
When to Use
- Use Phone Number Input for collecting a phone number.
When to Consider Something Else
- Use a Number Input if the numerical data is not associated with a phone number.
- Use a prompt if you need to select a country by itself outside of the context of a phone number.
- A Phone Number Input should not be used for dialing a phone number.
Behaviors
Selecting a Country Code
Tapping the pill in the Phone Number Input invokes our Bottom Sheet, which follows the typical patterns found in our Prompts. Country codes are defaulted based on the user’s provided phone number. Once in the Prompt/Bottom Sheet, a user can either cancel their decision (closing the bottom sheet), select a new country code, or search for a country code. Country codes are first listed by Frequently Used, then by country in alphabetical order. Upon selection of a new currency, users should be redirected back to their preceding screen with their new selection. Please note that the location of the input on the screen should remain the same to prevent a disorienting experience.
Frequently Used
When opening the bottom sheet, countries are automatically sorted into two groups, frequently used and all countries. The frequently used section is pre-determined based on Workday’s global usage data. The all countries section is displayed alphabetically by default.
Searching for a Country Code
Country codes are alphabetically or numerically searchable by either their country/geographical region of origin, or the country code itself.
Inputtable Country Codes
The country code is automatically populated within the input field based on the selected pill. However, the country code may also be manually input/adjusted via numberpad by deleting the numerical code and entering a new one.
Inputting a Value
When selecting the input field instead of the pill, the Phone Number Input should enter its active state, where the numberpad simultaneously comes into view.
Phone Number Formatting
As phone numbers are entered they are automatically formatted based on the selected country code. Users do not need to enter any additional characters beyond numbers, such as parentheses for area codes or dashes between sections.
Variations
With Extension
This variation includes an extra input field at the end for phone number extensions. If the screen size is too small to accommodate both fields in one line then the extension field is placed below the phone number field stretching to 50% of the column width.
Without Extension
If product or design has determined that the extension is not needed for their use case, the extension field can be hidden.
Content Guidelines
When writing content for Phone Number Input, please refer to the placeholder and instructional text sections of Content’s UI Text recommendations.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for. For further information, contact the #ask-canvas-design or #ask-canvas-kitchannels on Slack.