Text Input

Playground

Visage's text input uses the native HTML text input, so can be used for its myriad input type values; use a value that is appropriate for the input's function. For instance, if the input represents a search field, use type="search" rather than the default of type="text".

And since our Text Input uses the native HTML input, it can use all of its other features, including placeholder text:

<TextInput placeholder="Placeholder text" />

<input class="stylized-input" type="text" placeholder="Placeholder text" />

Size

When space is a concern, you can set a text input to have a "mini" size, making it shorter.

<TextInput sizeVariant="mini" />

<input class="stylized-input stylized-input-mini" type="text" />

There is also a "mega" size, used for pages whose sole focus is to let the user input text.

<StandardForm>
  <FormField>
    <FormLabel sizeVariant="mega">Here's a label for the input.</FormLabel>
    <FormInputGroup>
      <TextInput
        sizeVariant="mega"
        placeholder="This is the placeholder text."
      />
      <FormError sizeVariant="mega">The error message for the input.</FormError>
    </FormInputGroup>
  </FormField>
</StandardForm>

<input
  type="text"
  class="stylized-input stylized-input-mega"
  placeholder="This is the placeholder text"
/>

Text input with floating label

With the "floating label" functionality, the label appears to sit inside the input, shifting once the user enters text.

If a "floating label" is too long for the input, it will ellipse the text. (This is a guardrail to prevent page layout from deforming.) Ellipsed text not a good user experience, so you should be careful not to let this happen; keep floating label text short.

<TextInputWithFloatingLabel>
  <TextInput />
  <TextInputFloatingLabel>Floating label</TextInputFloatingLabel>
</TextInputWithFloatingLabel>

<div class="input-with-floating-label">
  <input
    class="stylized-input"
    type="text"
    placeholder="A floating label"
    id="myExampleFloatingLabel"
  />
  <label for="myExampleFloatingLabel">Floating label</label>
</div>

Text input with button beside

A text input and a button can be grouped together. The input should then use the "floating label" feature.

<TextInputWithButtonBeside>
  <TextInputWithFloatingLabel>
    <TextInput />
    <TextInputFloatingLabel>Floating label</TextInputFloatingLabel>
  </TextInputWithFloatingLabel>
  <TextButton skin="primary">Go</TextButton>
</TextInputWithButtonBeside>

<div class="input-with-button input-with-button-beside" role="group">
  <div class="input-with-floating-label">
    <input
      class="stylized-input"
      type="text"
      placeholder="A floating label"
      id="myExampleFloatingLabel"
    />
    <label for="myExampleFloatingLabel">Floating label</label>
  </div>
  <button class="textbutton textbutton-skin-primary" type="button">Go</button>
</div>

Text input with icon inset

A text input can have an icon inset within it, where the icon is a Control Icon that's also a button. The typical use case is for searchbars, using the "searchbar" skin:

<TextInputWithButtonInset skin="searchbar">
  <TextInput />
  <ControlIcon component="button" iconType="search" />
</TextInputWithButtonInset>

<div
  class="
    input-with-button input-with-button-inset input-with-button-skin-searchbar
  "
  role="group"
>
  <input class="stylized-input" type="text" />
  <button class="control-icon control-icon-search"></button>
</div>

Labels, Errors, and Helper Text

Text Input supports an "error" skin for when the current value of the input is invalid:

<TextInput skin="error" />

<input type="text" class="stylized-input stylized-input-skin-error" />

In React, when you use a TextInput inside a FormField along with other components, the "error" skin will be automatically applied when a FormError component is present. You'll get some other convenience behaviors, including the input's label automatically having its for attribute associated with the input. See Form for more.

In vanilla, you can get the error skin by applying the class stylized-input-skin-error to the input.

Managing State in React

As is the case with most form elements, folks often want to "control" this component. Controlling a component means that you take ownership over its state rather than letting the browser manage the state for you. When you control component, you own the source of truth for the UI. This means that you don't need to query the DOM in order to determine the current value of the element. So, when it comes time to use the value of the element somewhere else (e.g. submitting the value to a back-end service) you can trust your stored state.

If you'd like to control a TextInput, you'll need store the current value somewhere (e.g. React state or a Redux store), and you'll need to provide a handler to update that value when the user interacts with the component.

e.g.

() => {
  const [value, setValue] = React.useState('')
  return (
    <TextInput value={value} onChange={event => setValue(event.target.value)} />
  )
}

If you don't care about the state of the TextInput, you can simply omit the value and onChange props. In this case, you may add the defaultValue prop in order to specify the initial value of the TextInput without committing to fully managing the state.

Guidelines

Designer Guidelines

• Where possible, assist the user with placeholder text to provide examples of what to enter.

Developer Guidelines

• Inputs default to a width of 100%, filling up their container — this is a best practice for responsive design. If you need to limit an input's width, constrain its container, e.g. by putting it into a grid element of a certain number of columns.

Accessibility Guidelines

• See the Accessibility Guidelines for Forms.

Components