Skip to content
Telescope
Components

Form control

Form control displays a labelled input and, optionally, associated validation text, help popover, and/or hint text.
This will be publicly visible
Error:
Names may not contain symbols

Features

  • Flexible and composable components to layout form elements.
  • Use hint text to give users clear guidance for data entry.
  • Explain complex concepts or aid first-time users with help popovers.
  • Automatically associate labels with Telescope form elements.

When to use

Use the Form control component to achieve consistency between layouts of various form elements and more easily ensure accessible forms. The component works in combination with all foundational Telescope form elements.

Examples

Label

The label of a form element should be clear and concise, ideally under three words. It should describe the value of the element and not what the user needs to do in order to fill it out properly.

Information:

If you're having trouble keeping label text short, consider using hint text.

Show code
<FormControl maxWidth="240px">
    <FormControl.Label>Name</FormControl.Label>
    <Input name="input" value="Jeppe Rindom" />
</FormControl>

Hiding the label

Never omit the label completely. In rare cases, you may want to hide the label visually. An example of this could be a search field placed near the top of a page, featuring a magnifying glass icon and/or a button labelled “Search”.

Show code
<FormControl maxWidth="240px">
    <VisuallyHidden>
        <FormControl.Label>Search</FormControl.Label>
    </VisuallyHidden>
    <Input placeholder="Search..." name="search" type="search" prefix={<Search size={16} />} />
</FormControl>

Hint text

Use hint text to give users clear guidance for data entry. Keep it brief and avoid repeating the label or other form details. If it feels redundant, try removing it. We keep help text above the input field to have the reading order match the visual order, which is needed for screen readers.

Information:

To explain complex concepts or aid first-time users, prefer help popovers.

Show code
<FormControl maxWidth="240px">
    <FormControl.Label>Name</FormControl.Label>
    <FormControl.HintText>This will be publicly visible</FormControl.HintText>
    <Input name="input" />
</FormControl>

Help popover

Use help popovers to aid first-time users or to clarify complex concepts. The help popover can contain interactive content and may be used to provide links for further information.

Information:

For information on how to properly fill a field, prefer hint text.

Show code
<FormControl maxWidth="240px">
    <FormControl.LabelWrapper>
        <FormControl.Label>Card limit</FormControl.Label>
        <FormControl.Help aria-label="Learn more about: Card limit">
            You can set two types of limits on cards: monthly limits reset at the beginning of every
            month, whereas total limits apply from when you first set them and have to be reset
            manually. <Link href="#">Read more</Link>
        </FormControl.Help>
    </FormControl.LabelWrapper>
    <Input name="input" />
</FormControl>

Error

Provide clear and helpful error messages that guide users toward a solution. Instead of merely stating the problem, ensure the message is specific and actionable. Avoid vague or shaming language.

Show code
<FormControl maxWidth="240px">
    <FormControl.Label>Tags</FormControl.Label>
    <Select name="tag" placeholder="Select tags" isInvalid options={[]} />
    <FormControl.Error>Select at least one tag.</FormControl.Error>
</FormControl>

Skeleton

Use a "skeleton" version of this component to display a loading state while data is being fetched. It provides a visual placeholder, giving users a preview of the UI structure before the actual content is loaded. This enhances the user experience by offering a more accurate representation of the final layout during data retrieval.

Show code
<FormControl skeleton>
    <FormControl.LabelWrapper>
        <FormControl.Label>Label text</FormControl.Label>
        <FormControl.Help>Help text</FormControl.Help>
    </FormControl.LabelWrapper>
    <FormControl.HintText>Optional help text, maximum two lines.</FormControl.HintText>
    <Input name="basic" isInvalid skeleton />
</FormControl>

Best practices

Refer to our Forms guidelines for general advice on forms structure, validation, and more.

Do

Use clear and concise labels.

Don't

Use vague or overly long labels.

Do

The date this invoice was issued to you

Use hint text to give users clear guidance for data entry.

Don't

Enter the invoice date below

Repeat the label or other form details in the hint text.

Do

Error:
Enter your credit card number.

Communicate error messages in a way that guides the user towards a solution.

Don't

Error:
Invalid field.

Simply state what’s wrong and leave users guessing as to how to resolve it.

Do

Mark the minority as required or optional.

Don't

Mark the majority and don't use asterisks.

Related components

  • Checkbox: A form element that enables users to make a binary choice (checked/unchecked).
  • Checkbox group: A form element that enables users to select multiple values from a list of options.
  • Currency input: An enhanced input field that provides visual and non-visual cues to a user when entering an amount of money in a specified currency.
  • Input: A form element that enables users to enter a single line of text.
  • Radio group: A form element that enables users to select a single value from a list of options.
  • Select: A form element that enables users to select a single or multiple values from a list of options.
  • Textarea: A form element that enables users to enter text on multiple lines.
Didn't find what you were looking for?
Let us know in #team-design-systems or make a request.
Edit this page