TextInput | Mineral UI

TextInput allows your app to accept a text value from the user. It supports any of the text-based input types, such as text, number or email.

Examples #

Import Syntax #

import TextInput from 'mineral-ui/TextInput';

Note

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

Uncontrolled #

Uncontrolled TextInputs behave just like HTML input 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.

<TextInput defaultValue="Hello World" />

Controlled #

In a controlled TextInput, 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 (
        <TextInput
          value={this.state.value}
          onChange={this.handleChange} />
      );
    }
  }

  return <MyForm />;
}

Placeholder Text #

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

<TextInput placeholder="12345-123" />

Disabled #

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

<TextInput defaultValue="Hello World" disabled />

Read Only #

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

<TextInput defaultValue="Hello World" readOnly />

Required #

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

<TextInput required />

Invalid #

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

<TextInput invalid />

Available Sizes #

TextInput is available in a few sizes.

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

Variants #

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

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

With Icons #

TextInputs can contain Icons at their start, end, or both.

() => {
  const icon = <IconCloud />;

  return(
    <DemoLayout>
      <TextInput iconStart={icon} />
      <TextInput iconEnd={icon} />
      <TextInput iconStart={icon} iconEnd={icon} />
    </DemoLayout>
  );
}

Prefix & Suffix #

TextInputs can have a prefix and/or suffix, most commonly used for specifying units.

() => {
  const icon = <IconCloud />;

  return(
    <DemoLayout>
      <TextInput type="number" prefix="$" />
      <TextInput type="number" suffix="cm" />
    </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>
          <TextInput inputRef={ref => { this.input = ref; }} />
          <Button onClick={ this.focus }>Focus the input</Button>
        </DemoLayout>
      )
    }
  }

  return <MyForm />;
}

TextInputs support right-to-left (RTL) languages. TextInputs with Icons are reversed when the direction theme variable is set to rtl. A subset of Icons that convey directionality will be reversed.

<div dir="rtl">
  <ThemeProvider theme={{ direction: 'rtl' }}>
    <DemoLayout>
      <TextInput iconStart={<IconBackspace />} defaultValue="مرحبا بالعالم" />
      <TextInput iconEnd={<IconBackspace />} defaultValue="مرحبا بالعالم" />
      <TextInput variant="success" defaultValue="مرحبا بالعالم" />
    </DemoLayout>
  </ThemeProvider>
</div>

FormField #

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

Last NameRequired

Surname, family name

<DemoLayout>
  <FormField
    input={TextInput}
    label="Last Name"
    caption="Surname, family name"
    iconStart={<IconAccountBox />}
    required />
</DemoLayout>

API & Theme #

TextInput Props #

The TextInput component takes the following React props.

Name	Type	Default	Description
defaultValue	string		Initial value of the input. Primarily for use with uncontrolled components
disabled	boolean		Disables the input
htmlSize	number \| string		HTML `size` attribute
iconEnd	React$Element<*>		Icon located at the end of the input
iconStart	React$Element<*>		Icon located at the start of the input
inputRef			ref for the input
invalid	boolean		Indicates that the value of the element is invalid
onChange			Called when input value changes
prefix	string \| React$Element<*>		Text to display before input value
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
rootProps	Object		Props to be applied directly to the root element, rather than the input
size	'small' \| 'medium' \| 'large' \| 'jumbo'	'large'	Available sizes
suffix	string \| React$Element<*>		Text to display after input value
type		'text'	Type of input. Not all types are equally supported across browsers.
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, TextInput applies undocumented properties, including as and css, to the input.

TextInput 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
TextInput_backgroundColor	theme.input_backgroundColor
TextInput_borderColor	theme.borderColor
TextInput_borderColor_active	theme.borderColor
TextInput_borderColor_focus	theme.borderColor
TextInput_borderColor_hover	theme.borderColor_theme_hover
TextInput_borderRadius	theme.borderRadius_1
TextInput_borderWidth	1px
TextInput_boxShadow_active	0 0 0 1px boxShadow_focusInner, 0 0 0 2px borderColor_theme_active
TextInput_boxShadow_focus	0 0 0 1px boxShadow_focusInner, 0 0 0 2px borderColor_theme_focus
TextInput_color	theme.color
TextInput_color_placeholder	theme.input_color_placeholder
TextInput_color_readOnly	theme.color_readOnly
TextInput_fontSize	theme.fontSize_ui
TextInput_fontSize_small	0.75em
TextInput_paddingHorizontal	theme.space_inset_md
TextInput_paddingHorizontal_small	theme.space_inset_sm
TextInputIcon_marginHorizontal	theme.space_inline_sm
TextInput_height_small	theme.size_small
TextInput_height_medium	theme.size_medium
TextInput_height_large	theme.size_large
TextInput_height_jumbo	theme.size_jumbo
TextInputIcon_color	theme.color_gray_40

Usage #

When/How to Use #

Use a TextInput to accept brief, free-form input from a user.

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

Be specific when choosing the type for your TextInput. Mobile devices will display different keyboards depending on the input type.

Provide additional attributes to aid frictionless interaction with your forms. E.g. autocorrect="off" on an input accepting a user's name.

Best Practices #

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

Name

Use a placeholder to hint the expected content.

Account Number

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

Use a prefix or suffix to specify the expected units for the input or other pertinent information.

Price

Length

Phone Number

Don't use a prefix or suffix as a field label.

Name

Use the appropriate type for the expected content. This is especially useful on mobile devices, as a specialized keyboard will be used.

Name

Date

Quantity

Phone Number

Website