Paste

Design System

Select

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#

A select allows users to select an option from a list in a form field.

About Select#

Select allows a user to make a selection from a list of options in a form field. By default, it will show the first option in the list. However, you can also set a different pre-selected option from your list to show.

What's the difference between select and combobox?#

At its most basic, a select has an options list that’s styled according to the browser default. A combo box has a Twilio-styled options list and can allow for additional functionality like typeahead.

Use a select when:

  • You need a native picker experience, especially on mobile devices.
  • Users will be selecting from a list of 4-10 options, or a sorted list of highly familiar options (e.g., alphabetical list of states or countries).
  • You need the component to work out-of-the-box across all operating systems and browsers.

Use a combobox when:

  • You need a Twilio-styled options list.
  • You need to show more than text in an option (e.g., text paired with an icon).
  • You need placeholder text in the field to show an example option, rather than a pre-selected option.
  • Users would benefit from typeahead functionality (e.g., autocomplete, search). For example, typeahead may be useful when users need to select from a list of more than 10 options.
  • You need to lazy load a much longer list of options to improve page load performance.

Accessibility#

  • Include a visible label on all form fields.
  • Each label must use the htmlFor prop that equals the id of the associated input.
  • 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#

Base Select#

The base select is the input without any supporting elements (e.g., label, help text, etc).

  • Options — The list of items contained in a select
  • Selected value — (Optional) The value that appears in the select on page load. By default, this is the first option in the list.

The select will fill the width of the container it’s placed in.

Select#

The select component should include the base select, along with supporting elements to compose a select form field that gives the user 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.
  • Optional field indicator — In a form where there are more required fields than optional fields, use an optional indicator to show users which fields they don’t have to fill out. In general, ask for information only when needed. Consider removing the optional fields.
  • 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 Select. This is done with the htmlFor prop on the label, and the id prop on the select. Those two need to match.

Please choose a Twilio product.

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

  • Prefix/suffix text - Text that can be used as a prefix or suffix to the value that is entered. Use prefix/suffix to help users format text.
  • Icon - Icons that can be placed in the same area as the prefix and suffix text. Icons should trigger an action (e.g., opening a popover).
+1
Select with prefix.
Select with suffix.

Select with default value#

To be consistent with React's documentation on best practices for native select elements, the selected attribute is not allowed in the API. You can instead select a defaultValue property for the select.

Select with option groups#

Use an OptionGroup to create groupings of options within the select element.

  • label - String that will be used as the group label, this is required.
Select a product to learn more.

States#

Select with inline error#

Avoid errors on selects by removing or disabling invalid options from the list of options.

If a user is able to choose an invalid option, change a select to its error state and add an inline error. 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.

The number you have selected is not configured for emergency calling.

Select with disabled options#

Use a disabled option as the default selected value if you have no valid option to safely default to and the field is required.

Otherwise, use disabled options sparingly. Most browsers show disabled option text with low contrast, so consider other ways you could communicate that an option is unavailable, if you need to at all.

Some options in this select are disabled.

Disabled select#

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 Input or consider another way of showing static information.

This select is currently disabled.

Composition Notes#

A select field should be composed with at least a label and a select.

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.

Options in a select#

Keep option text concise and simple. Option text will truncate when it’s longer than the width of the container. If choosing options requires more explanation, consider using a Checkbox instead and add help text for each option, or give more explanation through help text.

Use a safe and reversible option as the default selected value, or an option that tells users to choose from the list. For example, on page load, a select could show “Choose category" as the default value if there’s no safe default.

Use 4-10 options in a select, or a sorted list of highly familiar options (e.g., alphabetical list of states), since selects don’t allow for searching or filtering through options. Sort options logically (e.g., alphabetically, by value) or in an order that’s intuitive to your user.

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 “Choose a nickname for your reference only” as label text. Instead, use “Nickname” as a label and “Nickname is for your reference only. This won’t be displayed to recipients.” 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.

If you need to use more than 2 sentences to explain a field, link out to supporting docs or trigger a popover instead.

Required or optional field identifier#

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

In a form where there are fewer optional fields than required, use an optional indicator to show users which fields they don’t have to fill out. Otherwise, use required indicators to show users which fields they must fill out.

If a field is required and there’s no safe default selected value, default to a disabled option that tells users to choose an option (e.g., “Choose categories”). However, if the field is optional and there’s no safe default, keep the option enabled so that users can unselect.

Validation#

Disable or remove any options in a select that would result in an error if possible. Validate form fields on form submission.

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#

Disable or remove any options in a select that would result in an error if possible. If an error occurs, use inline error text to explain how to fix an error.

Ideally, help text should have enough information to help users prevent errors. If 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. 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. 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.

When to use a Select#

Use a select when:

  • You need a native picker experience, especially on mobile devices.
  • You need the component to work out-of-the-box across all operating systems and browsers.
Do

Sort options in a list logically (e.g., alphabetically, ascending, descending).

Don't

Don’t order options in a list randomly or in a “recommended” order that hasn’t been validated with users.

Do

Use a safe and reversible option as the default selected value, or an option that tells users to choose from the list. Prevent users from unintentionally submitting a default value in case they accidentally skip over a field.

Don't

Don’t restrict users to options that unnecessarily reinforce biases and discrimination, such as gender binaries. Consider whether you need this information at all. If so, pair a select with an input or allow users to opt out.

Do

Give users time to confirm their selection. Consider users who might select a wrong option accidentally.

Don't

Avoid triggering an action when a user selects an option. For example, don’t open a new page immediately after a user makes a selection. If they made the wrong selection, going back to the original page to make the right selection could be frustrating. Instead, allow users to make the selection, then confirm.

Do

Keep option text concise and simple. If choosing options require more explanation, expand in help text or consider using a checkbox instead.

Don't

Avoid long option text that may truncate if it’s longer than the width of the container.

HTTP action for voice webhook.
Do

Keep help text and error text concise and simple.

HTTP action for voice webook. This will be used to manage an incoming call. Please also configure your fallback url and method in case the primary handler fails.
Don't

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

Do

Include a visible label on every form field.

HTTP
Don't

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

Please sign in again to change the HTTP method.
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.

Select the clients you would like to test.
Do

Use a checkbox group to allow users to make multiple selections.

Don't

When possible, avoid allowing multiple selection on a select component.

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
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
Chevron
  • Icon: IconChevronDown, $space-20 from left
No

Usage Guide#

API#

Installation#

yarn add @twilio-paste/form

Usage#

import {Select, Option, FormLabel, FormHelpText} from '@twilio-paste/form';
<FormLabel htmlFor="foo" required>Foo</FormLabel>
<Select id="foo" name="foo" onChange={FOO} required>
<Option value="foo-bar">Foo Bar</Option>
<Option value="bar-foo">Bar Foo</Option>
</Select>
<FormHelpText variant="default">Please select one</FormHelpText>

Select Props#

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

PropTypeDescriptionDefault
idstringSets the id of the input. Should match the htmlFor of FormLabel. Required.null
namestringSets the name of the select. Required.null
valuestring, string[]Sets the value of the select. Expects an array when multiple is present. Required.null
childrenNonNullable>React.ReactNode>Must be Option or OptionGroup. Required.null
disabled?booleanDisables the input.false
insertBefore?React.ReactNodeAdd Prefix to the select input.null
insertAfter?React.ReactNodeAdd Suffix to the select input.null
required?booleanSets the input as required.false
hasError?booleanSets the input to an error state.false
onChange(event: React.ChangeEvent<HTMLSelectElement>)Required.null
onFocus?(event: React.MouseEvent<HTMLElement>)null
onBlur?(event: React.MouseEvent<HTMLElement>)null

Option Props#

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

PropTypeDescriptionDefault
idstringSets the id of the input. Should match the htmlFor of FormLabel. Required.null
namestringSets the name of the select. Required.null
valuestring, string[]Sets the value of the select. Expects an array when multiple is present. Required.null
disabled?booleanDisables the input.false

OptionGroup Props#

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

PropTypeDescriptionDefault
labelstringSets the label of the optgroup. Required.null
children<NonNullable>React.ReactNodeMust be Option. Required.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 Select. 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.