Input

The input component allows users to input a value. Inputs can be used for text, email, passwords and numbers.

Code

Installation

yarn add @twilio-labs/match formik

Usage

import { Formik } from "formik";
import { Input, Form } from "@twilio-labs/match/components";
const Component = () => (
<Formik initialValues={{ email: "" }} onSubmit={() => {}}>
<Form>
<Input name="email" label="Email Address" type="email" />
</Form>
</Formik>
);

Props

PropTypeDefaultDescription
namestringnull
labelstringnull
type?InputType'text''number', 'text', 'tel', 'url', 'email', 'password'
size?InputSize'normal''normal', 'small'
required?booleannullSets the input as required.
disabled?booleannullDisables the input.
readOnly?booleannullSets the input as readonly.
hideLabel?booleannullVisually hides the label.
placeholder?stringnullSets the input's placeholder text.
additional?stringnullSupporting validation instructions.
validate?(value: string) => stringnullOverrides built in validation.
noValidate?booleannullDisables built in validation.
minLength?numbernullMinimum character length.
maxLength?numbernullMaximum character length.

Guidelines

About Inputs

Inputs are interactive form controls that accept a single line of text from a user. By default, inputs accept any combination of letters number and symbols. They can be given constraints by setting the type attribute to one of number, tel, url, or email. Inputs with specific types may also provide customized keyboard layouts in browsers and devices that support dynamic keyboards.

Accessibility

Here are some quick accessibility tips to ensure a positive user experience for all users.

  • Always include a descriptive label for each Input.
  • Do not use placeholder text as a replacement for labels.
  • Use the most appropriate input type for the data requested (e.g. text, email, or url).
  • Use additional to provide information on how to pass the Input's validation.
  • Use error messages to provide information on how to correct invalid data.

Composition

All Inputs must include a label. A label may be visually hidden only if the purpose of the Input is abundantly apparent. The hideLabel prop will remove the label entirely and apply an aria-label to the input element for screen readers.

Labels should be short and descriptive with any instructional text belonging in additional. Keep supplemental additional text concise and relevant to the input's validation requirements.

When an Input contains invalid data, provide an error message with instructional cues on how to make the correction. Any additional text provided with the Input will be replaced by the error. Be sure to repeat any relevant information that would have been lost.

Inputs should only be used on a white background.

Do
  • Only use placeholder text when clarifying examples are required. Try not to overuse it as it can cause clutter and confusion for a user.
  • Use help text to provide additional information to the user that could help prevent errors.
  • Use disabled to show a user that an input can not be interacted with yet.
Don't
  • Don't use placeholder text for every field.
  • Don't use placeholder text to provide error preventing information.
  • Don't use disabled to show information in an input that can not be edited.

Examples

Input with Help Text

Labels and help text are controlled via the Input component props in order to ensure consistency and accessibility best practices.

Input with Error

Inputs come with basic constraint validation enabled by default. You may override the built in validation with the validate prop, or completely disable with noValidate. For more advanced validation please read the Formik documentation. Note that additional text is replaced by the validation error.

Disabled Input

Disabled form fields cannot be interacted with. Use a read-only field for showing static information which cannot be edited.

Read-only Input

Read-only inputs can be focused but cannot be edited. Use a read-only Input when a user should be able to select and copy the text within. An example of when to use a read-only input may be displaying a user's responses after a form has been submitted.