Skip to content

Input

Status: Stable

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.

Examples

Default

Placeholder

Error

Disabled

Design guidelines

Always include a label

  • Placeholder text is not a replacement for labels     .
  • 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.
DOUse succinct noun labels.
DON'TOmit the label; placeholder text is not 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.
DOIndicate if an input is optional in the label.
DON'TUse “*” 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.
DOUse multiple line heights for text message area.
DON'TTruncate the input value or placeholder.

Help message, placeholder, and tooltip

The help message, placeholder, and tooltips help the user understand the input and any additional context.

Purpose
Limitation
Help messageInformation to clarify the label, always available in the default state.Limit the help message to one line.
PlaceholderHints at the format of the input; not crucial information.Limited length depending on the width of the field; disappears when the user begins typing.
TooltipElaborates on non-essential but helpful information about the input. The user should be able to understand the input field without the tooltip.Users might not look at the contents of the tooltip.
DOPlace tooltip after the label.
DON'TRepeat 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'TValidate immediately after each character typed.
DON'TAdd an icon in the input field.

Swap help message with an error message when validation fails

DODisplay help message to help the user complete the field.
DOSwap help message with an error message; describe the most likely error.

Props

In addition to the props defined by this component, any props <input> takes, such as name, value, onChange, etc., are accepted.

<Input>

actionLabel

string

actionProps

{ onClick: (e: MouseEvent<HTMLButtonElement, MouseEvent>) => void; }

icon

Deprecated
ReactNode
Icon to be shown on the right side of the input.

id

string
ID for the input element.

inputRef

(instance: HTMLInputElement | null) => void | RefObject<HTMLInputElement>
Gives access to the input DOM node.

style

Deprecated
CSSProperties

type

string
Type attribute on the <input> element.

label

string
A label for the input

className

string
Class on outer container element

disabled

boolean

error

boolean
Flag to indicate if input is in an error (red outline) state. Use in conjunction with errorMessage to display a red error message.

fullWidth

boolean

feedbackMessages

Array<{
feedbackType: "error" | "info" | "success"
message: string
id?: string
}>
A list of feedback messages to show for the group.

helpMessage

ReactNode
Optional help text shown below the input

errorMessage

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

tooltip

ReactNode
Optional tooltip shown via an icon next to the label

tooltipPlacement

"bottom" | "left" | "right" | "top"
Positioning of tooltip

defaultValue

string | number | Array<string>

placeholder

string

inputMode

"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"
Hints at the type of data that might be entered by the user while editing the element or its contents

onFocus

FocusEventHandler<T>

onBlur

FocusEventHandler<T>

onChange

ChangeEventHandler<T>

name

string

value

string | number | Array<string>

autoComplete

string

maxLength

number

required

boolean

ref

(instance: any) => void | RefObject<any>