TextArea | Mineral UI

TextArea allows your app to accept a potentially lengthy text value from the user.

Examples #

Import Syntax #

import TextArea from 'mineral-ui/TextArea';

Note

TextAreas should be wrapped in a FormField to provide an accessible label and other features. Examples here omit labels for clarity and brevity.

Uncontrolled #

Uncontrolled TextAreas behave just like HTML textarea elements. The value is handled by the DOM. The only difference is that defaultValue must be used to set the initial value rather than value.

<TextArea defaultValue="Hello World" />

Controlled #

In a controlled TextArea, the value is handled by a React component. Set the value with the value prop and provide an onChange handler.

() => {
  class MyForm extends Component {
    constructor(props) {
      super(props);

      this.state = {
        value: 'Hello World'
      };

      this.handleChange = this.handleChange.bind(this);
    }

    handleChange(event) {
      this.setState({
        value: event.target.value
      });
    }

    render() {
      return (
        <TextArea
          value={this.state.value}
          onChange={this.handleChange} />
      );
    }
  }

  return <MyForm />;
}

Placeholder Text #

Provide a placeholder as a helpful prompt of the expected content.

<TextArea placeholder="Leave a comment" />

Disabled #

Use the disabled prop to indicate that the input is not available for interaction.

<TextArea defaultValue="Hello World" disabled />

Read Only #

The readOnly prop indicates that the input value cannot be modified by the user.

Hello World

<TextArea defaultValue="Hello World" readOnly />

Required #

The required prop on a TextArea does nothing visually on its own, but is important for accessibility. See FormField's Required and Validation examples for more information.

<TextArea required />

Invalid #

The invalid prop on a TextArea does nothing visually on its own, but is important for accessibility. See FormField's Validation example for more info.

<TextArea invalid />

Available Sizes #

TextArea is available in a few different sizes. Note that the rows prop is complementary to size and can be used to adjust the number of lines displayed. See the Rows example for more details.

<DemoLayout>
  <TextArea size="small" defaultValue="Small" />
  <TextArea size="medium" defaultValue="Medium" />
  <TextArea defaultValue="Large" />
  <TextArea size="jumbo" defaultValue="Jumbo" />
</DemoLayout>

Rows #

Use the rows prop to adjust the number of lines displayed. Note that the rows prop is complementary to size.

<DemoLayout>
  <TextArea rows={1} size="small" defaultValue="Small" />
  <TextArea rows={1} size="medium" defaultValue="Medium" />
  <TextArea rows={1} defaultValue="Large" />
  <TextArea rows={1} size="jumbo" defaultValue="Jumbo" />
</DemoLayout>

Auto Size #

Use the autoSize prop to automatically adjust the height of the input to fit the content. Note that you can also use this prop in conjunction with the rows and size props.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris ornare velit nec dui molestie posuere. Nulla facilisi. Nulla tempor turpis vel aliquam viverra. In eu sagittis elit. Integer scelerisque purus nulla, sit amet dictum ipsum elementum finibus. Suspendisse et erat nisl. Sed aliquet finibus odio, ut volutpat metus dictum sed. Nullam nunc mi, consequat sit amet magna ut, faucibus placerat tortor. Duis porttitor tellus vitae condimentum convallis. Fusce hendrerit, nunc vitae tempor tempor, urna dolor fringilla eros, non condimentum urna dui id tellus. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Pellentesque tempor metus eget ipsum volutpat, venenatis imperdiet lacus commodo. Morbi quis dictum urna, vel facilisis magna. Phasellus nec vehicula lectus. Nulla laoreet nisi nec varius rhoncus. Integer at risus blandit, commodo urna sed, viverra dui.

Duis vitae nisl dignissim, congue elit et, ornare dolor. Pellentesque eu dui pellentesque, vestibulum odio sit amet, vehicula ante. Curabitur et turpis velit. Pellentesque in tincidunt nulla. Aenean malesuada ornare condimentum. Vivamus maximus efficitur sem, non consectetur arcu pretium in. Integer sodales quis quam nec iaculis. Donec accumsan tortor et magna tristique euismod. Nullam pellentesque, ligula nec condimentum rhoncus, arcu dui mollis lectus, ac porttitor purus nisi sed lacus.

<DemoLayout>
  <TextArea spellCheck={false} defaultValue={loremIpsum} autoSize />
  <TextArea rows={1} defaultValue="Hello World" autoSize />
  <TextArea rows={1} size="small" defaultValue="Hello World" autoSize />
</DemoLayout>

Variants #

TextArea is available in a few variants, mostly for use with validation. Be sure to use the appropriate variant for your intent.

<DemoLayout>
  <TextArea variant="success" defaultValue="Success" />
  <TextArea variant="warning" defaultValue="Warning" />
  <TextArea variant="danger" defaultValue="Danger" />
</DemoLayout>

Input ref #

The following example demonstrates how to get a reference to the underlying input element.

() => {
  class MyForm extends Component {
    constructor() {
      super();

      this.focus = this.focus.bind(this);
    }

    focus() {
      this.input.focus();
    }

    render() {
      return (
        <DemoLayout>
          <TextArea inputRef={ref => { this.input = ref; }} />
          <Button onClick={ this.focus }>Focus the input</Button>
        </DemoLayout>
      )
    }
  }

  return <MyForm />;
}

Bidirectionality #

TextAreas support right-to-left (RTL) languages.

<div dir="rtl">
  <ThemeProvider theme={{ direction: 'rtl' }}>
    <TextArea defaultValue="مرحبا بالعالم" />
  </ThemeProvider>
</div>

FormField #

Use a FormField to provide an accessible label and other features as well as a more streamlined API.

CommentsRequired

Please keep comments brief and descriptive

<DemoLayout>
  <FormField
    input={TextArea}
    label="Comments"
    caption="Please keep comments brief and descriptive"
    rows={2}
    autoSize
    required />
</DemoLayout>

API & Theme #

TextArea Props #

The TextArea component takes the following React props.

Name	Type	Default	Description
autoSize	boolean		Automatically adjust the height of the input to fit the content
defaultValue	string		Initial value of the input. Primarily for use with uncontrolled components
disabled	boolean		Disables the input
inputRef			ref for the input
invalid	boolean		Indicates that the value of the element is invalid
onChange			Called when input value changes
readOnly	boolean		Indicates that the user cannot modify the value of the input
required	boolean		Indicates that the user must fill in a value before submitting a form
resizeable	boolean		Indicates whether input is resizable. Not currently supported in IE/Edge.
rootProps	Object		Props to be applied directly to the root element, rather than the input
rows	number		The number of visible text lines in the input
size	'small' \| 'medium' \| 'large' \| 'jumbo'	'large'	Available sizes
value	string		The initial value of the input. Primarily for use with controlled components. If this prop is specified, an onChange handler must also be specified. Also see `defaultValue`.
variant	'danger' \| 'success' \| 'warning'		Available variants

Note

Unlike most other components, which apply undocumented properties to the root element, TextArea applies undocumented properties, including as and css, to the textarea.

TextArea Theme Variables #

These variables can be used as hooks to override this component's style at either a local or global level. The theme referenced below is whatever theme is available from props to the instance of this component.

Variable	Value
TextArea_backgroundColor	theme.input_backgroundColor
TextArea_borderColor	theme.borderColor
TextArea_borderColor_active	theme.borderColor
TextArea_borderColor_focus	theme.borderColor
TextArea_borderColor_hover	theme.borderColor_theme_hover
TextArea_borderRadius	theme.borderRadius_1
TextArea_borderWidth	1px
TextArea_boxShadow_active	0 0 0 1px boxShadow_focusInner, 0 0 0 2px borderColor_theme_active
TextArea_boxShadow_focus	0 0 0 1px boxShadow_focusInner, 0 0 0 2px borderColor_theme_focus
TextArea_color	theme.color
TextArea_color_placeholder	theme.input_color_placeholder
TextArea_color_readOnly	theme.color_readOnly
TextArea_fontSize	theme.fontSize_ui
TextArea_fontSize_small	0.75em
TextArea_paddingHorizontal	theme.space_inset_md
TextArea_paddingHorizontal_small	theme.space_inset_sm
TextAreaIcon_marginHorizontal	theme.space_inline_sm
TextArea_paddingVertical_jumbo	0.90625em
TextArea_paddingVertical_large	0.53125em
TextArea_paddingVertical_medium	0.28125em
TextArea_paddingVertical_small	0.125em

Usage #

When/How to Use #

Use a TextArea to accept potentially lengthy, free-form input from a user.

TextAreas should always have an associated label for accessibility and so the user knows what information to provide. See FormField.

Best Practices #

Wrap TextArea in a FormField and provide a brief, descriptive label.

Name

Use a placeholder to hint at the expected content.

Comments

Don't use a placeholder as a field label. This is not accessible and a poor experience.