Paste

Design System

Input

All the basic form elements for Twilio Paste

Status
beta
Version
1.5.3
Sources
Abstract
Install
yarn add @twilio-paste/form — or — yarn add @twilio-paste/core

Guidelines#

An input allows users to enter text on a single line.

About Input#

Use an input when you want to allow a user to enter a single line of text. By default, text inputs allow users to enter any type of text (letters, numbers, and symbols). You can set the input to more specific types if needed.

Accessibility#

  • Include a visible label on all form fields.
  • Each lable must use the htmlFor prop that equals the id of the associated input.
  • Don't use placeholder text as a replacement for labels. It can be used to provide an example to users, but will disappear from the field when a user enters text. It's also not broadly supported by assistive technologies and won't display in older browsers.
  • Use one of 3 ways to label a form field:
    • Visible label with FormLabel (preferred)
    • Visible label that's associated to the input with aria-labelledby
    • Label directly using aria-label
  • Provide clear identification of required fields in the label or at the start of a form. If you use the required field indicator, include the form key at the start of the form.
    • Use the required prop to programatically indicate they are required to browsers.
  • Include inline error text with the error icon on any field that errors to make it visually clear that the field changed.
  • If the input has assicated help text or error text, include the aria-describedby prop on the input. This should match the id of the help or error text.

Examples#

Input#

The input component should include the base input, along with supporting elements to compose an input field that gives users the context they need to successfully fill it out.

  • Label — A label should be included for every form field and provide a short title for its associated input.
  • Required field indicator — In a form where there are fewer or as many required fields as optional, use a required indicator to show users which fields are required to be filled out.
  • Help text — Text that's placed below the field to help users prevent an error and describe what makes the form field successful.

Hot accessibility tip

Make sure to connect the FormLabel to the FormInput. This is done with the htmlFor prop on the label, and the id prop on the input. Those two need to match.

If the input has any associated help text, the input should also use the aria-describedby prop that equals the id of the help text. This ensures screen readers know the help text ties directly to the input.

Please enter a valid email

Input with add-ons (prefix/suffix text or icons)#

  • Prefix/suffix text — Text that can be used as a prefix and/or suffix to the value that is entered. Use prefix/suffix to help users format text.
  • Icon — Icons can be placed in the same area as the prefix and suffix text. Icons should trigger an action (e.g., clearing a field) or in rare cases, provide further context to what value should be entered to make a field's purpose more immediately visible (e.g., a search icon).
$
Enter a dollar amount is USD format
Please enter a short title for your message

Input types#

How an input functions varies depending on the value of its type attribute. If a type attribute is not specified, the default type is text. The following type options are available:

text#

A single-line text input.

email#

An input for editing an email address. This looks like a text-type input but has validation parameters and relevant keyboard in browsers and devices with dynamic keyboards.

hidden#

An input that is not displayed but whose value is submitted to the server.

number#

An input for entering a number. It displays a numeric keypad in some devices with dynamic keypads.

password#

An input whose value is obscured. This input alerts a user if the site isn't secure.

readonly#

An input that can't be edited but can receive focus. Allows users to highlight the text in the field.

An input for entering search strings. It may include an icon in supporting browsers that can be used to clear the field. It displays a search key instead of enter key on some devices with dynamic keypads.

tel#

An input for entering a telephone number. It displays a telephone keypad in some devices with dynamic keypads.

States#

Input with inline error#

Change a form field to its error state and add an inline error if the value entered doesn't pass validation requirements.

An inline error is placed below the field to inform a user of any errors in their value. If help text exists, the error text should replace and repeat the help text.

Please enter a valid email

Disabled input#

Use a disabled form field to show users that they can't interact with the field.

If you want to show information that can't be edited, use a read-only form field or consider another way of showing static information.

Please enter a valid email

Read-only input#

Use a read-only form field when a field's value can't be changed, but users should be able to read or apply focus on the field. For example, use a read-only form field if a user needs to copy the value.

Please enter a valid email

Composition notes#

An input field must have at least a label and an input.

Positioning form fields#

Stack form fields vertically with $space-80 spacing between each field.

Avoid placing multiple form fields on the same horizontal row to help make it easier to scan a page vertically. Use the Grid component if you need to place form fields horizontally.

Labels and help text#

Labels should clearly describe the value being requested. They should be concise and descriptive, not instructional. To do this:

  • Use help text to provide instruction if needed. For example, don't use "Enter the registration code on the back of your SIM card below" as label text. Instead, use "SIM registration code" as a label and "Find the registration code on the back of your SIM card" as help text.
  • Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".

To support internationalization, avoid starting a sentence with the label and using the field to finish it since sentence structures vary across languages. For example, use "Call log expiration date" or "How long should logs be stored?". Don't use "Remove logs after:".

Give users enough information in help text to prevent input and formatting errors. Keep it concise and scoped to information that will help with validation. For example, use help text if a password field has specific requirements that a user should know prior to filling it out.

Required field indicator#

Ask for information only when needed. Consider removing the field otherwise.

Use required indicators to show users which fields they must fill out.

Validation#

Validate form fields on form submission.

Validating a form field when the user leaves the current field (on blur) can be helpful to check for syntax errors. However, this can be frustrating to users who tab through controls to navigate a page, and to screen reader users, who might not be able to detect that an error occurred on blur.

Don't prevent form submission by disabling the submit button. An error message can give more information than a disabled button can to help users figure out which fields are invalid.

Errors#

Use inline error text to explain how to fix an error.

Ideally, help text should have enough information to help users prevent errors. If help text exists and you need to show an error, the error text should replace and repeat the help text until the error has been resolved.

Error text should:

  • Be actionable. Explain how to fix an error and if reasonable, why it happened so that it might also be prevented in the future.
  • Be concise and simple, maybe even more than normal. Avoid jargon. Try to keep error text to 2 sentences or fewer.
  • Use the passive voice for input errors to avoid placing blame on the user. For example, "A friendly name is required."
  • Use the active voice for system errors. For example, "Our systems are currently down. Please contact our support team."

Optional compositional elements#

  • Prefix/suffix — Use a prefix or suffix to help users format their input and to provide more context about the value a user is entering. For example, you could prefix or suffix a field with a currency symbol, or use suffix to append a character counter. Make sure to consider internationalization when using prefixes or suffixes since formatting may differ across languages. For example, currency symbols are placed on the left in American English, while they're placed on the right in French. Don't use prefix/suffix text as a replacement for a label.
  • Icon — Use an icon if you need to give the user additional controls for the field. For example, use an icon to clear a field on click, removing the need for users to manually delete their entered value. Place icon buttons that trigger an action on the right side of the field. If you need 2 actions on a field (e.g., popover trigger and clear field), place the icon button that affects the field value on the right, and the other icon on the left.
  • Placeholder — Use a placeholder when you want to give an example of the type of data a user should enter, mainly to help with recall. For example, when asking for links to social media profiles, you could give examples of a few social media sites. Placeholders should be used in addition to the label and not as a replacement since they'll disappear when a user begins entering their own value. If you need to show supporting instructions, use help text instead.

When to use an input#

Use an input when users are expected to enter less than a single line of text, or text that's shorter than a sentence.

Do

Use an input to encourage short text entry.

Don't

Don't use an input when text entry is expected to be longer than the width of the input since users may need to review the text before submission. Use a textarea instead.

Limit to 60 characters
Do

If you limit the length of text entry, show a character counter and explain to users in help text why their entry is restricted.

Don't

Don't have a character limit if you can't explain to the user why their text entry is restricted.

Please enter a valid email
Do

Use help text to help users prevent errors and fill out a form field correctly.

Don't

Don't use placeholder text for validation instructions.

Do

Use the correct input type to help users format their text correctly and bring up dynamic keypads.

Don't

Don't use the default input type if there's a more specific one that can help users enter valid text more efficiently.

Use the following format: (###) ###-####
Do

Keep help text and error text concise and simple. If you need to use more than 2 sentences to explain a field, link out to supporting docs or trigger a popover instead.

Go to your settings. Then click on email addresses. After doing that, copy and paste your email address in this field.
Don't

Don't use more than 2 sentences in help text or error text.

Do

Include a visible label on every form field.

Name
Don't

Don't use prefix/suffix text as a replacement for a label.

Do

Use a disabled form field to show users that they can't interact with the field, but that it could potentially be enabled through another UI element.

Don't

Don't use a disabled form field to show information that can't be edited. Instead, use a read-only form field or consider another way of showing static information.

Anatomy#

PropertyDefault tokenModifiable?
Label text
  • $font-size-30
  • Default: $color-text, $font-weight-semibold
  • Disabled: $color-text-weak, $font-weight-semibold
No
Required field indicator
  • 4px size (0.25rem)
  • Background: $color-background-required
No
Box Shadow
  • Default: $shadow-border
  • Hover: $shadow-border-primary-dark
  • Disabled: $shadow-border-light
  • Error: $shadow-border-error
  • Error hover: $shadow-border-error-dark
No
Background
  • Default: $color-background-body
  • Disabled, Readonly: $color-background
No
Prefix/suffix
  • Background: $color-background
  • Border: $color-border-light
No
Prefix/suffix text
  • Default: $color-text
  • Disabled: $color-text-weak
No
Value text
  • $font-size-30
  • Default, Readonly: $color-text
  • Disabled: $color-text-weak
No, but it can take any children
Placeholder text $color-text-weak, italicNo
Help text$color-text-weak, $font-size-30No
Inline error
  • Text: $color-text-error, $font-size-30
  • Icon: IconError, $color-text-error, $icon-size-30
No
Spacing
  • Label:
    • Bottom: $space-10
    • Between label and required indicator: $space-20
  • Input:
    • Left padding: $space-40
    • Top, right, bottom padding: $space-30
  • Prefix/suffix padding: $space-30
  • Help text:
    • Top: $space-20
  • Inline error:
    • Spacing between icon and text: $space-20
    • Top: $space-20
No

Usage Guide#

API#

Installation#

yarn add @twilio-paste/form - or - yarn add @twilio-paste/core

Usage#

import {FormInput, FormLabel, FormHelpText} from '@twilio-paste/form';
const Component = () => (
<>
<FormLabel htmlFor="foo" required>
foo
</FormLabel>
<FormInput aria-describedby="foo_text" id="foo" name="foo" type="text" placeholder="foo" onChange={FOO} required />
<FormHelpText id="foo_text">Please enter some text</FormHelpText>
</>
);

FormInput Props#

All the valid HTML attributes for input are supported including the following props:

PropTypeDescriptionDefault
idstringSets the id of the input. Should match the htmlFor of FormLabel. Required.null
type'text', 'email', 'hidden', 'number', 'password', 'search', 'tel'Sets the type of the input. Required.null
namestringSets the name of the input. Required.null
valuestringSets the value of the input. Required.null
placeholder?stringSets the placeholder of the input.null
disabled?booleanDisables the input.false
readOnly?booleanSets the input to readonly.false
required?booleanSets the input as required.false
hasError?booleanSets the input to an error state.false
onChange?(event: React.MouseEvent<HTMLElement>)null
onFocus(event: React.MouseEvent<HTMLElement>)null
onBlur?(event: React.MouseEvent<HTMLElement>)null

FormLabel Props#

All the valid HTML attributes for label are supported including the following props:

PropTypeDescriptionDefault
children?ReactNodenull
htmlForstringSets the for of the label. Should match the id of FormInput. Required.null
disabled?booleanShows the input is disabled.false
required?booleanShows the input is required.false
marginBottom?'space0', 'space10''space10'

FormHelpText Props#

All the valid HTML attributes (role, aria-*, type, and so on) including the following props:

PropTypeDescriptionDefault
children?ReactNodenull
marginTop?'space0', 'space20''space20'
variant?'error'Sets the help text to an error state'space20'

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.5.3 (2020-05-28)

Note: Version bump only for package @twilio-paste/form

1.5.2 (2020-05-27)

Note: Version bump only for package @twilio-paste/form

1.5.1 (2020-05-27)

Bug Fixes#

1.5.0 (2020-05-22)

Features#

  • form: export styled InputElement, add FormControlWrapper (04da812)

1.4.1 (2020-05-20)

Note: Version bump only for package @twilio-paste/form

1.4.0 (2020-05-13)

Bug Fixes#

  • form: remove required onChange from input (49b2c77)

Features#

  • select: update knobs for select stories (#430) (dc48f63)

1.3.4 (2020-05-07)

Note: Version bump only for package @twilio-paste/form

1.3.3 (2020-05-07)

Bug Fixes#

  • form: updates to tokens used in borders (e97e49e)

1.3.2 (2020-05-04)

Note: Version bump only for package @twilio-paste/form

1.3.1 (2020-05-01)

Note: Version bump only for package @twilio-paste/form

1.3.0 (2020-05-01)

Features#

  • select: Select, Option, and OptionGroup (#399) (761924e)

1.2.0 (2020-04-25)

Features#

  • form: add radio and checkbox components (1b68f8d)
  • form: updates to form label (72c37c2)

1.1.10 (2020-04-22)

Bug Fixes#

  • tokens: Add shadow-border-input-* aliases, tokens to themes (#400) (a553100)

1.1.9 (2020-04-20)

Note: Version bump only for package @twilio-paste/form

1.1.8 (2020-04-17)

Note: Version bump only for package @twilio-paste/form

1.1.7 (2020-04-15)

Note: Version bump only for package @twilio-paste/form

1.1.6 (2020-04-08)

Bug Fixes#

  • form: package dependencies updated to be correct (48bb40f)

1.1.5 (2020-04-07)

Note: Version bump only for package @twilio-paste/form

1.1.4 (2020-04-07)

Bug Fixes#

  • form: use color prop, update tests and snapshots (1f7313a)

1.1.3 (2020-04-02)

Note: Version bump only for package @twilio-paste/form

1.1.2 (2020-04-01)

Bug Fixes#

  • form: enable safely spreading props to form controls (#367) (6a12a9d)

1.1.1 (2020-04-01)

Note: Version bump only for package @twilio-paste/form

1.1.0 (2020-04-01)

Features#

  • form: add autoresizing to the textarea component (#365) (9cc5b7b)

1.0.4 (2020-03-31)

Bug Fixes#

  • form: remove box-shadow, inherit font family (#362) (5cac3c4)

1.0.3 (2020-03-30)

Bug Fixes#

  • form: change hover for disabled and readonly input and textarea (#361) (7592de5)

1.0.2 (2020-03-28)

Note: Version bump only for package @twilio-paste/form

1.0.1 (2020-03-27)

Bug Fixes#

  • form: remove input type hidden box shadow (#359) (25301f4)

1.0.0 (2020-03-25)

Bug Fixes#

  • form: change FormHelperText to FormHelpText (7d8954d)

BREAKING CHANGES#

  • form: The FormHelperText component has been renamed to FormHelpText to align with the Sketch symbol library

0.2.3 (2020-03-24)

Bug Fixes#

  • form: switch from theme-tokens to theme package dep (9d26cda)

0.2.2 (2020-03-20)

Note: Version bump only for package @twilio-paste/form

0.2.1 (2020-03-17)

Note: Version bump only for package @twilio-paste/form

0.2.0 (2020-03-17)

Features#

0.1.2 (2020-03-17)

Note: Version bump only for package @twilio-paste/form

0.1.1 (2020-03-11)

Note: Version bump only for package @twilio-paste/form

0.1.0 (2020-03-11)

Features#

0.0.2 (2019-10-29)

Note: Version bump only for package @twilio-paste/form

0.0.1 (2019-08-15)#

Note: Version bump only for package @twilio-paste/form

Support

If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.

Contributing

The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.