Developer mode
Opens components on the React tab by default.
Your bookmarks

InputGroup

Combines related inputs for a form.

When you have multiple input fields for related information, such as a date of birth with a day, a month, and a year, group them together to make it clear they’re about the same thing. This lets you label and validate the group as a whole, rather than just individual fields.

Component status

Figma
Designing
Web (React)
Released
iOS (Swift)
n/a
Android (Kotlin)
n/a
Docs
Released

Content structure

Label: provides a clear description of what users should fill in; input divider: clearly separates inputs within the group; Select (component): specifies options users can choose from. InputField (component): specifies one type of input expected of users; error: guides users on how to solve any problems and overrides errors for individual inputs in the group.

Guidelines

Use for closely related fields       

Input groups override the settings of individual fields to present a coherent whole. This means they’re great for a couple of fields that make a single unit.

They’re not good at grouping many fields, such as everything that goes into building an address. For those cases, use visual spacing, logical headers, and other structure to make it clear what fields are related.

Use labels

Labels serve to clearly present what is expected. They are especially important for people who won’t see other visual cues. But they also help everyone know exactly what to enter.

For the label, use short descriptive phrases, ideally nouns that make the request clear. See our patterns for form labels for some examples.

Use help and error messages

For more complicated fields, sometimes labels aren’t enough. You want to include any necessary information as clear as possible to help users complete the fields.

Use help messages to guide users before they enter anything and clear calm error messages when there’s a problem with what they entered.

Remember that such messages are likely to invoke negative feelings, so be positive and focused on solutions to any problems.

Help messages

import InputField from "@kiwicom/orbit-components/lib/InputField";
import InputGroup from "@kiwicom/orbit-components/lib/InputGroup";
import Select from "@kiwicom/orbit-components/lib/Select";
() => {
  const [month, setMonth] = React.useState("")
  return (
    <InputGroup
      flex={["8 8 15em", "1 1 4em", "2 2 6em"]}
      label="Departure"
      help="Select a month and enter a day and year for your departure."
    >
      <Select
        value={month}
        help="This text is not displayed"
        placeholder="Month"
        options={[
          {
            label: "January",
            value: "January",
          },
          {
            label: "February",
            value: "February",
          },
          {
            label: "March",
            value: "March",
          },
          {
            label: "April",
            value: "April",
          },
          {
            label: "May",
            value: "May",
          },
          {
            label: "June",
            value: "June",
          },
          {
            label: "July",
            value: "July",
          },
          {
            label: "August",
            value: "August",
          },
          {
            label: "September",
            value: "September",
          },
          {
            label: "October",
            value: "October",
          },
          {
            label: "November",
            value: "November",
          },
          {
            label: "December",
            value: "December",
          },
        ]}
        onChange={(event) => setMonth(event.target.value)}
      />

      <InputField
        help="This text is not displayed"
        placeholder="DD"
        maxValue={31}
        minValue={1}
        type="number"
      />
      <InputField
        help="This text is not displayed"
        placeholder="YYYY"
        minValue={2020}
        type="number"
      />
    </InputGroup>
  )
}

Error messages

import InputField from "@kiwicom/orbit-components/lib/InputField";
import InputGroup from "@kiwicom/orbit-components/lib/InputGroup";
import Select from "@kiwicom/orbit-components/lib/Select";
() => {
  const [month, setMonth] = React.useState("")
  const [year, setYear] = React.useState(2000)
  return (
    <InputGroup
      flex={["8 8 15em", "1 1 4em", "2 2 6em"]}
      label="Departure"
      help="Select a month and enter a day and year for your departure."
      error={
        year < new Date().getFullYear()
          ? "Enter a year that is not in the past"
          : ""
      }
    >
      <Select
        value={month}
        error="This text is not displayed"
        placeholder="Month"
        options={[
          {
            label: "January",
            value: "January",
          },
          {
            label: "February",
            value: "February",
          },
          {
            label: "March",
            value: "March",
          },
          {
            label: "April",
            value: "April",
          },
          {
            label: "May",
            value: "May",
          },
          {
            label: "June",
            value: "June",
          },
          {
            label: "July",
            value: "July",
          },
          {
            label: "August",
            value: "August",
          },
          {
            label: "September",
            value: "September",
          },
          {
            label: "October",
            value: "October",
          },
          {
            label: "November",
            value: "November",
          },
          {
            label: "December",
            value: "December",
          },
        ]}
        onChange={(event) => setMonth(event.target.value)}
      />

      <InputField
        error="This text is not displayed"
        placeholder="DD"
        type="number"
      />
      <InputField
        error="This text is not displayed"
        placeholder="YYYY"
        value={year}
        type="number"
        onChange={(event) => {
          setYear(parseInt(event.target.value, 10))
        }}
      />
    </InputGroup>
  )
}

Include placeholder examples

When you have additional information or helpful examples, include placeholder text to help users along. 

Remember that placeholder text is visually less important, low in contrast, and disappears once users enter anything. So do not include anything necessary to complete the field.

The placeholder text must be added to each field, rather than the input group as a whole.

Related components

Field components

If you need to collect information that can’t be presented as a single unit, use the appropriate field for the data type, such as an input field, select, input file, or input stepper.