TextField

A text field allows a user to enter text with a keyboard into a single-line input form element.

Installyarn add @diallink-corp/convergo-react-textfield
Version4.1.2
Usageimport {TextField} from '@diallink-corp/convergo-react-textfield'

Uncontrolled Value

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

<TextField label="Email" defaultValue="alexander@diallink.com" />
<TextField
  label="Email"
  defaultValue="alexander@diallink.com"
/>
<TextField
  label="Email"
  defaultValue="alexander@diallink.com"
/>

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('alexander@diallink.com');

  return (
    <div>
      <TextField 
        label='Email' 
        value={value} 
        onChange={setValue} 
      />

      <div>Value: {value}</div>
    </div>
  );
}
function Example() {
  const [value, setValue] = useState(
    'alexander@diallink.com'
  );

  return (
    <div>
      <TextField
        label="Email"
        value={value}
        onChange={setValue}
      />

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

function Example() {
  const [
    value,
    setValue
  ] = useState(
    'alexander@diallink.com'
  );

  return (
    <div>
      <TextField
        label="Email"
        value={value}
        onChange={setValue}
      />

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

Labeling

A TextField component should be labeled with a visual text through the label prop. If the TextField 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.

<TextField label='Email' />
<TextField label='Email' />
<TextField label="Email" />

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of the TextField 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.

<TextField label='Email' labelPlacement='top end' />
<TextField label='Email' labelPlacement='top end' />
<TextField
  label="Email"
  labelPlacement="top end"
/>

Label Position

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

<TextField label='Email' labelPlacement='side end' />
<TextField label='Email' labelPlacement='side end' />
<TextField
  label="Email"
  labelPlacement="side end"
/>

Required

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

<TextField label='Email' isRequired />
<TextField label='Email' isRequired />
<TextField
  label="Email"
  isRequired
/>

Validation

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

function Example() {
  const [value, setValue] = useState('alexander@inperiu');

  const emailRegExp =
    /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
  const isValidEmail = emailRegExp.test(value);

  return (
    <TextField
      label="Email"
      value={value}
      onChange={setValue}
      errorMessage={!isValidEmail && 'The email you entered is invalid.'}
    />
  );
}

function Example() {
  const [value, setValue] = useState('alexander@inperiu');

  const emailRegExp =
    /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
  const isValidEmail = emailRegExp.test(value);

  return (
    <TextField
      label="Email"
      value={value}
      onChange={setValue}
      errorMessage={!isValidEmail &&
        'The email you entered is invalid.'}
    />
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState(
    'alexander@inperiu'
  );

  const emailRegExp =
    /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
  const isValidEmail =
    emailRegExp.test(
      value
    );

  return (
    <TextField
      label="Email"
      value={value}
      onChange={setValue}
      errorMessage={!isValidEmail &&
        'The email you entered is invalid.'}
    />
  );
}

Also you can use the input pattern attribute to control the value with a regular expression.

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

  const regExp = /^[0-9]{3,6}$/;
  const isValid = regExp.test(value);

  return (
    <TextField 
      label='One-Time Code'
      value={value}
      onChange={setValue}
      pattern={regExp.source}
      title='3 to 6 digits'
      placeholder='Must be 3-6 digits'
      errorMessage={!isValid && 'One-Time Code must be 3-6 digits in length.'} 
    />
  );
}
function Example() {
  const [value, setValue] = useState('');

  const regExp = /^[0-9]{3,6}$/;
  const isValid = regExp.test(value);

  return (
    <TextField
      label="One-Time Code"
      value={value}
      onChange={setValue}
      pattern={regExp.source}
      title="3 to 6 digits"
      placeholder="Must be 3-6 digits"
      errorMessage={!isValid &&
        'One-Time Code must be 3-6 digits in length.'}
    />
  );
}

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

  const regExp =
    /^[0-9]{3,6}$/;
  const isValid = regExp
    .test(value);

  return (
    <TextField
      label="One-Time Code"
      value={value}
      onChange={setValue}
      pattern={regExp
        .source}
      title="3 to 6 digits"
      placeholder="Must be 3-6 digits"
      errorMessage={!isValid &&
        'One-Time Code must be 3-6 digits in length.'}
    />
  );
}

Description

To give further instructions or more verbose examples to the user about a TextField 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.

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

Placeholder

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

<TextField label='Email' placeholder='test@diallink.com' />
<TextField label='Email' placeholder='test@diallink.com' />
<TextField
  label="Email"
  placeholder="test@diallink.com"
/>

Contextual Help

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

<TextField 
  label='Email' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
/>
<TextField
  label="Email"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
/>
<TextField
  label="Email"
  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 TextField component can be disabled via the isDisabled prop.

<TextField label="Email" defaultValue="alexander@diallink.com" isDisabled />
<TextField
  label="Email"
  defaultValue="alexander@diallink.com"
  isDisabled
/>
<TextField
  label="Email"
  defaultValue="alexander@diallink.com"
  isDisabled
/>

Read Only

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

<TextField label="Email" defaultValue="alexander@diallink.com" isReadOnly />
<TextField
  label="Email"
  defaultValue="alexander@diallink.com"
  isReadOnly
/>
<TextField
  label="Email"
  defaultValue="alexander@diallink.com"
  isReadOnly
/>

Icons

You can optionally add an icon to the TextField component.

<TextField
  label="Search"
  iconName="MagnifyingGlassIcon"
  iconVariant="outline"
/>
<TextField
  label="Search"
  iconName="MagnifyingGlassIcon"
  iconVariant="outline"
/>
<TextField
  label="Search"
  iconName="MagnifyingGlassIcon"
  iconVariant="outline"
/>

Accessibility

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

API