TextArea

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/components-base

Package version

1.6.1

Loading...

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

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

Introduction

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

Use the TextArea component to collect long-form information such as product feedback or support queries. The TextArea height will automatically increase when new lines are added - this behavior can be limited within the theme.

Guidance

Controlled component

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

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

Loading...

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

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

Uncontrolled component

If it is not necessary to control the TextArea 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.

Loading...

<TextArea label="Order instructions" initialValue="Leave at the main door" validation="success" />

<TextArea label="Order instructions" initialValue="Leave at the main door" validation="success" />

Loading...

<TextArea label="Order instructions" validation="error" feedback="This field must be filled." />

<TextArea label="Order instructions" validation="error" feedback="This field must be filled." />

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.

Loading...

<TextArea label="Special requests" hint="Please include order number" />

<TextArea label="Special requests" hint="Please include order number" />

• 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

Using a tooltip

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

Loading...

<TextArea label="Describe your inquiry" hint="Please include customer ID" tooltip="Inquiries will be addressed by our staff ASAP. We will reach out if the query cannot be fulfilled. Please check your confirmation email for your customer ID." />

<TextArea
  label="Describe your inquiry"
  hint="Please include customer ID"
  tooltip="Inquiries will be addressed by our staff ASAP. We will reach out if the query cannot be fulfilled. Please check your confirmation email for your customer ID."
/>

info

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

Appearance

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

Loading...

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

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

Loading...

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

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

Loading...

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

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

Accessibility

TextArea 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.

Platform considerations

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