PhoneNumberField

A phone number field allows a user to enter numbers with a keyboard into a single-line input form element. The output will be formatted like a phone number based on its country code and locale.

Uncontrolled Value

By default, the PhoneNumberField component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultValue to set a value by default.

<PhoneNumberField label='Cell' defaultValue='3059015650' />

<PhoneNumberField label='Cell' defaultValue='3059015650' />

<PhoneNumberField
  label="Cell"
  defaultValue="3059015650"
/>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a value prop as well as an onChange handler to modify the value when the user types.

function Example() {
  const [value, setValue] = useState('3059015650');

  return (
    <div>
      <PhoneNumberField 
        name='phoneNumber'
        label='Cell' 
        value={value} 
        onChange={setValue} 
      />

      <div>Value: {value}</div>
    </div>
  );
}

function Example() {
  const [value, setValue] = useState('3059015650');

  return (
    <div>
      <PhoneNumberField 
        name='phoneNumber'
        label='Cell' 
        value={value} 
        onChange={setValue} 
      />

      <div>Value: {value}</div>
    </div>
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(
    '3059015650'
  );

  return (
    <div>
      <PhoneNumberField
        name="phoneNumber"
        label="Cell"
        value={value}
        onChange={setValue}
      />

      <div>
        Value: {value}
      </div>
    </div>
  );
}

Labeling

A PhoneNumberField component should be labeled with a visual text through the label prop. If the PhoneNumberField does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<PhoneNumberField label='Cell' />

<PhoneNumberField label='Cell' />

<PhoneNumberField label="Cell" />

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of the PhoneNumberField component is displayed on the left side of the input. For right-to-left (RTL) languages, such as Arabic, this is flipped. You can control the position of the label through the labelPlacement prop.

<PhoneNumberField label='Cell' labelPlacement='top end' />

<PhoneNumberField label='Cell' labelPlacement='top end' />

<PhoneNumberField
  label="Cell"
  labelPlacement="top end"
/>

Label Position

By default, the label of the PhoneNumberField component is displayed above the input. With the labelPlacement prop this placement can be adjusted to be on the side of the input.

<PhoneNumberField label='Cell' labelPlacement='side end' />

<PhoneNumberField label='Cell' labelPlacement='side end' />

<PhoneNumberField
  label="Cell"
  labelPlacement="side end"
/>

Required

To indicate to the user that the PhoneNumberField is required you can use the isRequired prop.

<PhoneNumberField label='Cell' isRequired />

<PhoneNumberField label='Cell' isRequired />

<PhoneNumberField
  label="Cell"
  isRequired
/>

Validation

The PhoneNumberField component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop.

<PhoneNumberField label="Cell" errorMessage="Test error message" />

<PhoneNumberField
  label="Cell"
  errorMessage="Test error message"
/>

<PhoneNumberField
  label="Cell"
  errorMessage="Test error message"
/>

Description

To give further instructions or more verbose examples to the user about a PhoneNumberField you can provide a description prop. Avoid using error like tone of voice of the message. If an errorMessage prop is provided it will replace the description.

<PhoneNumberField
  label="Cell"
  description="An enumeration of the essential qualities of a thing or species"
/>

<PhoneNumberField
  label="Cell"
  description="An enumeration of the essential qualities of a thing or species"
/>

<PhoneNumberField
  label="Cell"
  description="An enumeration of the essential qualities of a thing or species"
/>

Placeholder

To give further instructions or examples to the user about a PhoneNumberField you can provide a placeholder prop.

<PhoneNumberField label='Cell' placeholder='23' />

<PhoneNumberField label='Cell' placeholder='23' />

<PhoneNumberField
  label="Cell"
  placeholder="23"
/>

Contextual Help

To offer the user contextual help, the PhoneNumberField supports passing a contextualHelp prop, that accepts a ReactNode.

<PhoneNumberField 
  label='Cell' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
/>

<PhoneNumberField
  label="Cell"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

<PhoneNumberField
  label="Cell"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>

Disabled

The PhoneNumberField component can be disabled via the isDisabled prop.

<PhoneNumberField label="Cell" defaultValue="3059015650" isDisabled />

<PhoneNumberField
  label="Cell"
  defaultValue="3059015650"
  isDisabled
/>

<PhoneNumberField
  label="Cell"
  defaultValue="3059015650"
  isDisabled
/>

Read Only

The PhoneNumberField component can be marked as read only via the isReadOnly prop.

<PhoneNumberField label="Cell" defaultValue="3059015650" isReadOnly />

<PhoneNumberField
  label="Cell"
  defaultValue="3059015650"
  isReadOnly
/>

<PhoneNumberField
  label="Cell"
  defaultValue="3059015650"
  isReadOnly
/>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.

API