Input

Status: Stable

Latest released: March 2020

Current version: v9.10.10

Storybook
GitHub

Inputs enable a user to enter or edit data to influence or change their experience.

Hero Image
  1. Field: The area or box that holds the input.
  2. Label: The text above the field that describes the information needed.
  3. Placeholder (optional): The pre-populated, gray text in the field that hints at the format of the information required.
  4. Help message (optional): The text below the field that helps a user understand the input and successfully enter a correct value.

Variants

Default

Placeholder

Error

Disabled


Design guidelines

Always include a label

  • Place the label above the container.
  • Choose short, descriptive words.
  • Use sentence case without punctuation.
  • Keep length to one line.
  • Refer to Foundational Page for more details.
Do
Use succinct noun labels.
Don't
Skip a label.

Use the label to indicate optional inputs

  • Use “(optional)” to indicate if the input is optional.
  • Required inputs do not need extra labels or copy.
Do
Indicate if an input is optional in the label.
Don't
Use “*” to indicate required.

Adjust the size of the field to the expected amount of input

  • Field size should set expectations to how much input is required.
  • Inputs for shorter values, like a phone number, should be smaller, and inputs for longer values, like a message, should be larger.
Do
Use multiple line heights for text message area.
Don't
Truncate the input value or placeholder.

Use copy to set the right amount of context

Placeholder text, help text and tooltips help the user understand the input and any additional context.

Placeholder text (optional)

  • Hints at the format of the input.
  • Should be a realistic example value when it’s a number (like $5,000).
  • Disappears as soon as user clicks in.

Help message (optional)

Clarifies the label, e.g. “City” could mean where the user was born, where the user currently resides, etc., whereas “City you currently live in” clarifies the information needed.

Tooltip (optional)

  • Elaborates on non-essential but helpful information about the input.
  • The user should be able to understand the input field without the tooltip.
  • Tooltips generally have longer copy but still aim to keep it concise (around 2 sentences). Learn more about tooltips.
Do
Place tooltip after the label.
Don't
Repeat information in label, placeholder or help message.

Field validation

Show error when the input is no longer in focus. Use animated transition delay of .4 milliseconds.

Don't
Validate immediately after each character typed.
Don't
Add an icon in the input field.

Development

import Input from '@nerdwallet/react-input';
<Input />;

Props

<Input>

error

boolean

Show the input in an error visual state.

Default

false

icon

node

@deprecated prop to show icon on the right side of the input.

Default

null

fullWidth

boolean

When true, sets width to 100% on the input.

Default

false

disabled

boolean

Disable interaction and change.

Default

false

type

string

Type attribute on the <input> element.

Default

'text'

className

string

Class on the <input> element.

Default

null

inputRef

Function

Gives access to the input dom node

Default

null

label

string

Label for the input. Components should almost always include a label.

Default

null

errorMessage

node

Optional text to be shown indicating the user is in an error state.

Default

null

helpMessage

node

Optional help text shown below the input.

Default

null

tooltip

node

Optional tooltip shown via an icon next to the label.

Default

null

tooltipPlacement

'top' | 'right' | 'bottom' | 'left'

Positioning of tooltip.

Default

null

dangerouslyForceFocusStyling

boolean

Force the component to use its focus styles.

Default

false

dangerouslyForceHoverStyling

boolean

Force the component to use its hover styles.

Default

false