TextInput

Library: UDS Base
Repository: github.com/telus/universal-design-system
Package: npmjs.com/package/@telus-uds/components-base
Package version: 1.6.1

<TextInput
  label="Label"
  hint="A usually much longer hint below"
  hintPosition="below"
  tooltip="Tooltip content"
/>

<TextInput
  label="Label"
  hint="A usually much longer hint below"
  hintPosition="below"
  tooltip="Tooltip content"
/>

Introduction

import { TextInput } from '@telus-uds/components-base'

A basic text input component. Use in forms or individually to receive user's input.

Guidance

Controlled component

If it is required that the state of the TextInput be controlled by the application or other external methods, value and onChange props must be passed to the TextInput.

function ControlledInput() {
  const [value, setValue] = React.useState('')
  const [validation, feedback] = React.useMemo(() => {
    if (value && value.length > 6) {
      return ['error', 'The value must be shorter than 6 characters']
    } else if (value && value.length > 0) {
      return ['success', 'Yay! The value has less than 6 characters']
    }
    return [
      undefined,
      'This example shows an error if longer than 6 characters and success otherwise'
    ]
  }, [value])

  return (
    <TextInput
      label="Controlled"
      validation={validation}
      feedback={feedback}
      value={value}
      onChange={setValue}
    />
  )
}

function ControlledInput() {
  const [value, setValue] = React.useState('')
  const [validation, feedback] = React.useMemo(() => {
    if (value && value.length > 6) {
      return ['error', 'The value must be shorter than 6 characters']
    } else if (value && value.length > 0) {
      return ['success', 'Yay! The value has less than 6 characters']
    }
    return [
      undefined,
      'This example shows an error if longer than 6 characters and success otherwise'
    ]
  }, [value])

  return (
    <TextInput
      label="Controlled"
      validation={validation}
      feedback={feedback}
      value={value}
      onChange={setValue}
    />
  )
}

If the TextInput value should not be changed by user input, a readOnly prop must be provided.

<TextInput label="Read only" readOnly value="won't change" />

<TextInput label="Read only" readOnly value="won't change" />

Uncontrolled component

If it is not necessary to control the TextInput state, you can create one without a value prop. In this case its value can be accessed within the onChange callback.

Getting feedback for entered values

Use the feedback prop to give the user feedback regarding their input (keep it as brief as possible). You can affirm that the user's input was correct, or highlight errors that must be corrected by setting the validation prop.

<TextInput label="Username" initialValue="guest12345" validation="success" />

<TextInput label="Username" initialValue="guest12345" validation="success" />

<TextInput
  label="Email"
  initialValue="guest@telus.com"
  validation="error"
  feedback="That email is already associated with another account."
/>

<TextInput
  label="Email"
  initialValue="guest@telus.com"
  validation="error"
  feedback="That email is already associated with another account."
/>

This component does not perform input validations, as that is an application level concern. You will need to track the value of your form fields and perform any required data validations either client side or server side, depending on the context.

Supplying a hint

Use a hint to succinctly clarify attributes of the expected input data, such as the expected format, or an indicator that the field is optional. It is a more usable and accessible option than the HTML placeholder attribute.

<TextInput label="Transit number" hint="5 digits" />

<TextInput label="Transit number" hint="5 digits" />

hint can be used beside the label (inline) or below
- Label and inline hint text should not exceed 40 characters total, otherwise, use hint text below the label
The hint should not be longer than 85 characters
The hint should not wrap more than 3 lines on all viewport sizes
Developers can use hintPosition to re-position the hint below the label if the text supplied to the inline hint wraps

<TextInput
  label="Quick view"
  hintPosition="below"
  hint="Enter the account number in the box below to go to the overview page for that account."
/>

<TextInput
  label="Quick view"
  hintPosition="below"
  hint="Enter the account number in the box below to go to the overview page for that account."
/>

When a more in-depth explanation is needed to fill out a TextInput properly, additional instructions may be provided to the tooltip prop.

<TextInput
  label="Customer ID"
  tooltip="You can find your customer ID in the account confirmation email."
/>

<TextInput
  label="Customer ID"
  tooltip="You can find your customer ID in the account confirmation email."
/>

info

In order to support more advanced usages all additional props will be passed down to the React Native's TextInput component. See React Native documentation for supported props and React Native Web documentation for their implementation on the web.

Appearance

TextInput has no visual variants, but its appearance may change based on the validation and inactive props.

<TextInput label="Last name" validation="success" initialValue="Potter" />

<TextInput label="Last name" validation="success" initialValue="Potter" />

<TextInput label="Last name" validation="error" />

<TextInput label="Last name" validation="error" />

<TextInput label="Inactive" inactive initialValue="can't touch this" />

<TextInput label="Inactive" inactive initialValue="can't touch this" />

Accessibility

TextInput is accessible to screen readers on both native platforms and Web. It will be announced with the label prop if it is provided, and optionally described with the hint, tooltip and feedback.

info

Due to React Native's implementation of TextInput it's not possible to access the current value of the input by passing a ref. You can only access it within the onChange callback.

Props

Name	Type	Default	Description
variant	objectOf	{}	System variant prop, see variants for more details
value	string		If the input's state is to be controlled by a parent component, use this prop together with the `onChange` to pass down and update the lifted state.
initialValue	string		Use this to set the initial value of an uncontrolled input. Updating `initialValue` will not update the actual value.
inactive	bool		Disables all user interactions with the input.
readOnly	bool		Makes it impossible to change the input's value.
onChange	func		Use to react upon input's value changes. Required when the `value` prop is set. Will receive the input's value as an argument.
tokens	custom		System tokens prop, see tokens for more details

TextInput

Introduction​

Guidance​

Controlled component​

Uncontrolled component​

Getting feedback for entered values​

Supplying a hint​

Using a tooltip​

info

Appearance​

Accessibility​

info

Props​

Introduction

Guidance

Controlled component

Uncontrolled component

Getting feedback for entered values

Supplying a hint

Using a tooltip

Appearance

Accessibility

Props