TextArea
- Library
- UDS Base
- Repository
- github.com/telus/universal-design-system
- Package
- npmjs.com/package/@telus-uds/ds-allium
- Package version
- 1.14.0
Introduction
import { TextArea } from '@telus-uds/ds-allium'
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.
If the TextArea value should not be changed by user input, a readOnly prop must be provided.
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.
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.
hintcan 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
hintshould not be longer than 85 characters - The
hintshould not wrap more than 3 lines on all viewport sizes - Developers can use
hintPositionto re-position thehintbelow thelabelif the text supplied to the inlinehintwraps
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.
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.
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
The component is available on both native platforms and web.
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 |
|---|---|---|---|
| inactive | bool | Disables all user interactions with the input. | |
| initialValue | string | Use this to set the initial value of an uncontrolled input. Updating 'initialValue' will **not** update the actual 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. | |
| readOnly | bool | Makes it impossible to change the input's value. | |
| tokens | custom | System tokens prop, see tokens 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. | |
| variant | objectOf | {} | System variant prop, see variants for more details |
Tokens
In exceptional circumstances, the following tokens can be passed to this component to override its default styles. Do not do this unless absolutely necessary. Read more about overriding styles.
View Tokens
| Prop Name | Token Property | Token Type |
|---|---|---|
| tokens | minLines | integer |
| maxLines | integer | |
| backgroundColor | color | |
| color | color | |
| borderWidth | border | |
| borderColor | color | |
| borderRadius | radius | |
| paddingTop | size | |
| paddingBottom | size | |
| paddingLeft | size | |
| paddingRight | size | |
| outerBackgroundColor | color | |
| outerBorderWidth | border | |
| outerBorderColor | color | |
| fontName | fontName | |
| fontWeight | fontWeight | |
| fontSize | fontSize | |
| lineHeight | lineHeight | |
| icon | icon | |
| iconSize | size | |
| iconColor | color |
Figma
Variants
TextArea has no visual variants, but its appearance may change based on the validation and inactive props.
Feedback
- Spotted a problem with this component? Raise an issue on GitHub
- See any existing issues for this component
- Contact the team on slack in #ds-allium-support