InputGroup

InputGroup visually groups related form fields and actions together.

Basic Usage

To implement the InputGroup component, you need to import it first:

import { InputGroup } from '@react-ui-org/react-ui';

And use it:

React.createElement(() => {
  const [fruit, setFruit] = React.useState('apple');
  const options = [
    {
      label: 'Apple',
      value: 'apple',
    },
    {
      label: 'Pear',
      value: 'pear',
    },
    {
      label: 'Cherry',
      value: 'cherry',
    },
  ];
  return (
    <InputGroup label="Your favourite fruit">
      <SelectField
        label="Your favourite fruit"
        onChange={(e) => setFruit(e.target.value)}
        options={options}
        value={fruit}
      />
      <TextField
        label="Variety"
        placeholder="Eg. Golden delicious"
      />
      <Button label="Submit" />
    </InputGroup>
  );
})

See API for all available options.

General Guidelines

• Use input group to group related fields and actions that a user can take. Input fields and buttons should not be grouped just to save space on the screen.

• While the number of child inputs is not limited, keep in mind the layout of InputGroup is currently not responsive: the inputs do not shrink nor wrap. Make sure your inputs fit their container, especially on small screens.

• In the background, InputGroup uses the fieldset element. Not only it improves the accessibility of the group, it also allows you to make use of its built-in features like disabling all nested inputs or pairing the group with a form outside. Consult the MDN docs to learn more.

• InputGroup currently supports grouping of TextField, SelectField, and Button components.

• To group Buttons only, use the ButtonGroup component which is designed specifically for that purpose.

Sizes

All existing field and button sizes are also available on the input group level: small, medium, and large.

<InputGroup
  label="Small size"
  size="small"
>
  <TextField label="Input" />
  <Button label="Submit" />
</InputGroup>
<InputGroup label="Medium size">
  <TextField label="Input" />
  <Button label="Submit" />
</InputGroup>
<InputGroup
  label="Large size"
  size="large"
>
  <TextField label="Input" />
  <Button label="Submit" />
</InputGroup>

Shared Property

You can set the size property directly on InputGroup to be shared for all fields and buttons inside the group. This property is then passed over to individual elements. At the same time, it cannot be overridden on the fields' or buttons' level. While technically possible, from the design point of view it's undesirable to group elements of totally different types or sizes.

Invisible Label

In some cases, it may be convenient to visually hide the group label. The label remains accessible to assistive technologies. Labels of individual inputs are always visually hidden.

While it may be acceptable for login screens with just a few fields or for other simple forms, it's dangerous to hide labels from users in most cases. Keep in mind you should provide another visual clue so users know what to fill into the input.

<InputGroup
  isLabelVisible={false}
  label="First and last name"
>
  <TextField
    label="First name"
    placeholder="Eg. John"
  />
  <TextField
    label="Last name"
    placeholder="Eg. Doe"
  />
  <Button label="Submit" />
</InputGroup>

Horizontal layout

The default vertical layout is very easy to use and work with. However, there are situations where horizontal layout suits better — and that's why React UI supports this kind of layout as well.

<InputGroup
  label="Horizontal layout"
  layout="horizontal"
>
  <TextField label="Label" />
  <Button label="Submit" />
</InputGroup>

States

Disabled State

Disables all fields and buttons inside the group.

<InputGroup disabled label="Disabled group">
  <TextField label="Label" />
  <Button label="Submit" />
</InputGroup>

Validation States

Validation states visually present the result of validation of the grouped inputs. Input group's validation state is taken from its child inputs. You should always provide validation messages for states other than valid directly through validationTexts prop so users know what happened and what action they should take or what options they have. These messages are not semantically tied to the children elements, the connection should be expressed in textual form in the actual message. The individual children elements must not show any validationText, they only show their respective validationState. Validation messages passed to input elements' validationText prop will be ignored.

👉 While there is a required property to visually denote the whole input group is required, there is no functional effect as there is no such HTML attribute for the underlying <fieldset> element.

<InputGroup
  label="First and last name"
  required
  validationTexts={[
    "First name must be filled in.",
    "Last name must be filled in.",
  ]}
>
  <TextField
    label="First name"
    placeholder="Eg. John"
    required
    validationState="invalid"
  />
  <TextField
    label="Last name"
    placeholder="Eg. Doe"
    required
    validationState="invalid"
  />
  <Button label="Submit" />
</InputGroup>
<InputGroup
  label="First and last name"
  required
  validationTexts={[
    "Last name should not include any digits.",
  ]}
>
  <TextField
    label="First name"
    placeholder="Eg. John"
    required
    value="John"
  />
  <TextField
    label="Last name"
    placeholder="Eg. Doe"
    required
    validationState="warning"
    value="123Doe"
  />
  <Button label="Submit" />
</InputGroup>
<InputGroup
  label="First and last name"
  required
>
  <TextField
    label="First name"
    placeholder="Eg. John"
    required
    validationState="valid"
    value="John"
  />
  <TextField
    label="Last name"
    placeholder="Eg. Doe"
    required
    validationState="valid"
    value="Doe"
  />
  <Button label="Submit" />
</InputGroup>

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify any HTML attribute you like. All attributes that don't interfere with the API of the React component are forwarded to the root <fieldset> HTML element. This enables making the component interactive and helps to improve its accessibility.

👉 For the full list of supported attributes refer to:

• <fieldset> HTML element attributes
• React common props

API

Theming

Custom Property	Description
--rui-InputGroup__gap	Gap between elements
--rui-InputGroup__inner-border-radius	Inner border radius of elements