Label

A Label is text that provides a visible and accessible name to a form element.

<>
  <Label htmlFor="email_address" required>Email address</Label>
  <Input aria-describedby="email_help_text" id="email_address" name="email_address" type="email" placeholder="example@twilio.com" onChange={() => {}} required/>
  <HelpText id="email_help_text">Use your work email address.</HelpText>
</>

Guidelines

About Label

A Label is text that is placed above a form field to describe the form field. 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:".

Accessibility

Include a visible label on all form fields.
Each label must use the htmlFor prop that equals the id of the associated input.
The text of the label needs to remain same. It should not change based on the state of the input.

(information)

Make sure to connect the Label to the Input. This is done with the htmlFor prop on the label, and the id prop on the form field. Those two need to match.

Examples

Label with Input

<>
  <Label htmlFor="email_address" required>Email address</Label>
  <Input aria-describedby="email_help_text" id="email_address" name="email_address" type="email" placeholder="example@twilio.com" onChange={() => {}} required/>
  <HelpText id="email_help_text">Use your work email address.</HelpText>
</>

Label with Select

<>
  <Label htmlFor="author">Select an author</Label>
  <Select id="author">
    <Option value="baldwin">James Baldwin</Option>
    <Option value="brown">adrienne maree brown</Option>
    <Option value="butler">Octavia Butler</Option>
    <Option value="coates">Ta-Nehisi Coates</Option>
    <Option value="lorde">Audre Lorde</Option>
    <Option value="nnedi">Nnedi Okorafor</Option>
  </Select>
</>

Label with TextArea

<>
  <Label htmlFor="message" required>Message (at least 120 characters)</Label>
  <TextArea onChange={()=>{}} onChange={()=>{}} aria-describedby="message_help_text" id="message" name="message" placeholder="Enter message" required />
  <HelpText id="message_help_text">Enter at least 120 characters</HelpText>
</>

Label with DatePicker

const RequiredDatePicker = (props) => {
  const uidDP = useUID();
  const uidHT = useUID();
  return (
    <>
      <Label htmlFor={uidDP} required>
        When was the abolition of slavery announced in Galveston Bay, Texas (also known as Juneteenth)?
      </Label>
      <DatePicker required id={uidDP} aria-describedby={uidHT} {...props} />
      <HelpText id={uidHT}>
        Enter a date above.
        <Anchor href="https://nmaahc.si.edu/blog-post/historical-legacy-juneteenth" showExternal>
          Read more about Juneteenth
        </Anchor>
      </HelpText>
    </>
  );
};
render(<RequiredDatePicker />)

Label with TimePicker

<>
  <Label htmlFor="appointment-time">What time is your appointment?</Label>
  <TimePicker id="appointment-time" aria-describedby="appointment-time-help-text" />
  <HelpText id="appointment-time-help-text">Select a time above.</HelpText>
</>

States

Default Label

<>
  <Label htmlFor="email_address">Email address</Label>
  <Input aria-describedby="email_help_text" id="email_address" name="email_address" type="email" placeholder="example@twilio.com" onChange={() => {}}/>
  <HelpText id="email_help_text">Use your work email address.</HelpText>
</>

Required Label

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

<>
  <Label htmlFor="email_address" required>Email address</Label>
  <Input aria-describedby="email_help_text" id="email_address" name="email_address" type="email" placeholder="example@twilio.com" onChange={() => {}} required/>
  <HelpText id="email_help_text">Use your work email address.</HelpText>
</>

Disabled Label

Use the disabled prop if a the label is associated with a disabled form field to show users that they can't interact with the field.

<>
  <Label htmlFor="email_disabled" disabled>Email address</Label>
  <Input aria-describedby="email_disabled_help_text" id="email_disabled" name="email_disabled" type="email" placeholder="example@twilio.com" onChange={() => {}} disabled />
  <HelpText id="email_disabled_help_text">Use your work email address.</HelpText>
</>

When to use a Label

Use a Label to clearly describe the the form field.

Name

Do

Use Label in composition with a form element.

Tell us your life story

Don't

Don't use Label as a stand-alone component.

Name

Do

Include a visible label on every form field.

Name

Don't

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