# InputPhoneNumber

Automatically format your user's phone number as they type.

InputPhoneNumber's auto-format is set to always be `(***) ***-****` and doesn't
expect the user to type in their country code. Because phone numbers vary so
much around the world, typing more than 10 digits will turn off the
auto-formatting.

## Design & usage guidelines

Due to the auto-format, this component is restricted to only be used as a
controlled component. That means the `value` and `onChange` props are required,
unlike the other input components.

## Content guidelines

The `prefix` prop can be used to add a
[country code](/storybook/web/?path=/story/components-forms-and-inputs-inputphonenumber--with-country-code)
to the input. The country code won't be added to the value that the component
would return. It is simply for visual purposes.

InputPhoneNumber can also have a
[custom pattern](/storybook/web/?path=/story/components-forms-and-inputs-inputphonenumber--custom-pattern)
if you wish to use a different format for the phone number.

Lastly, InputPhoneNumber will respect the format of the
[initial value](/storybook/web/?path=/story/components-forms-and-inputs-inputphonenumber--initial-value)
it is given. It will only start auto-formatting the existing value when the user
edits the input.

## Clearable

* **while-editing**: shows the clear button only while focused and when there is
  a value. When focus leaves the field and its controls, the button is hidden.
* **always**: shows the clear button whenever there is a value, even when
  blurred. Never shown when the field is empty.
* The clear button is not shown when the field is `disabled` or `readonly`.


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onChange` | `(value: string) => void` | Yes | — | onChange handler that provides the new value (or event) |
| `value` | `string` | Yes | — | Set the component to the given value. |
| `autocomplete` | `boolean | AutocompleteTypes` | No | — | Determines if browser form autocomplete is enabled. Note that "one-time-code" is experimental and should not be used ... |
| `clearable` | `Clearable` | No | — | Add a clear action on the input that clears the value.  You should always use `while-editing` if you want the input t... |
| `description` | `ReactNode` | No | — | Further description of the input, can be used for a hint. |
| `disabled` | `boolean` | No | — | Disable the input |
| `id` | `string` | No | — | A unique identifier for the input. |
| `inline` | `boolean` | No | — | Adjusts the form field to go inline with a content. This also silences the given `validations` prop. You'd have to us... |
| `invalid` | `boolean` | No | — | Highlights the field red to indicate an error. |
| `loading` | `boolean` | No | — | Show a spinner to indicate loading |
| `name` | `string` | No | — | Name of the input. |
| `onBlur` | `(event?: FocusEvent<Element, Element>) => void` | No | — | Blur callback. |
| `onEnter` | `(event: KeyboardEvent<Element>) => void` | No | — | A callback to handle "Enter" keypress. This will only run if Enter is the only key. Will not run if Shift or Control ... |
| `onFocus` | `(event?: FocusEvent<Element, Element>) => void` | No | — | Focus callback. |
| `onValidation` | `(message: string) => void` | No | — | Callback to get the the status and message when validating a field @param message |
| `pattern` | `string` | No | `"(***) ***-****"` | A pattern to specify the format to display the phone number in. For example if you want to display the format for [De... |
| `placeholder` | `string` | No | — | Text that appears inside the input when empty and floats above the value as a mini label once the user enters a value... |
| `prefix` | `Affix` | No | — | Adds a prefix label and icon to the field |
| `readonly` | `boolean` | No | — | Prevents users from editing the value. |
| `required` | `boolean` | No | — | Shows a "required" validation message when the component is left empty. |
| `showMiniLabel` | `boolean` | No | `true` | Controls the visibility of the mini label that appears inside the input when a value is entered. By default, the plac... |
| `size` | `"small" | "large"` | No | — | Adjusts the interface to either have small or large spacing. |
| `suffix` | `{ onClick: () => void; readonly ariaLabel: string; readonly icon: IconNames; readonly label?: string; } | { onClick?: never; ariaLabel?: never; readonly label?: string; readonly icon?: IconNames; }` | No | — | Adds a suffix label and icon with an optional action to the field |
| `validations` | `RegisterOptions` | No | — | Show an error message above the field. This also highlights the the field red if an error message shows up. |
| `version` | `1` | No | — | Experimental: Determine which version of the FormField to use. Right now this isn't used but it will be used in the f... |
