Skip to main contentSkip to docs navigation
View on GitHub

Input Groups

Create powerful, flexible input combinations with Chassis CSS's advanced input group system that seamlessly pairs form controls with text, icons, buttons, and more.

On this page
@layer components
Depends onForm Input
Context tokens

Overview

Chassis CSS's Input Groups enable you to create cohesive, composite form controls by combining inputs with complementary elements. Built on our design token system, input groups provide semantic markup with responsive sizing and full theming support.

@
@example.com
https://
Enter your website domain without the protocol
HTML
<div class="input-group mb-medium">
  <span class="input-addon">@</span>
  <input type="text" class="form-input" placeholder="Username" aria-label="Username">
</div>

<div class="input-group mb-medium">
  <input type="text" class="form-input" placeholder="Recipient's username" aria-label="Recipient's username">
  <span class="input-addon">@example.com</span>
</div>

<div class="mb-medium">
  <label for="basic-url" class="form-label">Website URL</label>
  <div class="input-group">
    <span class="input-addon">https://</span>
    <input type="text" class="form-input" id="basic-url" aria-describedby="url-help">
  </div>
  <!-- Form helps placed outside the input group -->
  <div class="form-help" id="url-help">Enter your website domain without the protocol</div>
</div>

Key features and benefits

  • Flexible composition: Combine any Chassis CSS form control with addons on either or both sides
  • Intelligent border handling: Automatic border radius management for seamless appearance
  • Responsive sizing: Single size class affects all elements in the group
  • Accessibility-focused: Built-in ARIA support and keyboard navigation
  • Theme integration: Works with both default and alternate form styles, plus dark mode support
  • CSS variable customization: Easy to adapt to your design system

Remember to place form helps and validation feedbacks as siblings after the input group, not inside it. This ensures proper spacing, styling, and accessibility for error states and help text.

Addon types

Chassis CSS offers several addon types that can be combined to create the exact input experience you need.

Text addons

The .input-addon class creates text-based addons with appropriate spacing, borders, and background styling. These addons inherit form theming and automatically adapt to the input group's size.

$ .00
HTML
<div class="input-group mb-medium">
  <span class="input-addon">$</span>
  <input type="text" class="form-input" aria-label="Amount">
  <span class="input-addon">.00</span>
</div>

<div class="input-group">
  <label class="input-addon" for="productDescription">Description</label>
  <textarea class="form-input" id="productDescription"></textarea>
</div>

Text addons automatically share borders with adjacent form controls to create a unified appearance, while maintaining appropriate spacing and visual hierarchy.

Icon addons

Combine the .input-addon class with an <svg> element to create borderless icon elements that appear to be integrated directly into the input field. Chassis CSS handles positioning and spacing automatically.

HTML
<div class="input-group mb-medium">
  <span class="input-addon"><svg class="icon" aria-hidden="true"><use href="#lock-solid"></use></svg></span>
  <input type="password" autocomplete="current-password" class="form-input" placeholder="Password" aria-label="Password">
  <button class="input-addon" type="button" aria-label="Show password">
    <svg class="icon" aria-hidden="true"><use href="#eye-solid"></use></svg>
  </button>
</div>

<div class="input-group">
  <span class="input-addon"><svg class="icon" aria-hidden="true"><use href="#search-solid"></use></svg></span>
  <input type="search" class="form-input" placeholder="Search" aria-label="Search" disabled>
</div>

Icon addons are positioned absolutely relative to their input, with intelligent spacing that adapts to input size. When disabled inputs are detected, icon colors are automatically adjusted for proper visual state indication.

Button addons

Add any Chassis CSS button directly to an input group to create action-oriented form controls. Buttons maintain their styling while visually integrating with the input.

HTML
<div class="input-group mb-medium">
  <input type="text" class="form-input" placeholder="Search term" aria-label="Search term">
  <button class="button primary" type="button">Search</button>
</div>

<div class="input-group">
  <button class="button outline secondary" type="button">Options</button>
  <input type="text" class="form-input" aria-label="Text input with button addon">
</div>

Buttons within input groups are given a higher z-index than inputs to ensure proper layering, especially when focused. This improves both visual consistency and interaction clarity.

Form controls as addons

Checks and radios can be incorporated into input groups by nesting them within .input-addon elements. This creates compact, multi-purpose controls while maintaining accessibility.

HTML
<div class="input-group mb-medium" role="group" aria-label="Newsletter subscription">
  <div class="input-addon">
    <input class="check-input mt-0" type="checkbox" value="" aria-label="Subscribe to newsletter">
  </div>
  <input type="email" class="form-input" placeholder="Email address" aria-label="Email for newsletter">
</div>

<div class="input-group" role="group" aria-label="Task with priority">
  <div class="input-addon">
    <input class="check-input mt-0" type="radio" name="priority" value="high" aria-label="High priority">
  </div>
  <input type="text" class="form-input" placeholder="Task description" aria-label="Task description">
</div>

When using form controls within addons, add the .mt-0 class to the .check-input to ensure proper vertical alignment within the container.

Layout capabilities

Chassis CSS's input groups provide multiple layout options to handle various interface requirements efficiently.

Multiple addons

Create more complex interfaces by including multiple addons on either side of an input. Each addon maintains proper styling and spacing while creating a unified control.

Name @
$ USD
HTML
<div class="input-group mb-medium">
  <span class="input-addon">Name</span>
  <span class="input-addon">@</span>
  <input type="text" class="form-input" aria-label="Username with multiple prefixes">
</div>

<div class="input-group">
  <input type="text" class="form-input" aria-label="Currency amount">
  <span class="input-addon">$</span>
  <span class="input-addon">USD</span>
</div>

Multiple addons work together through Chassis CSS's advanced border radius management system, which ensures appropriate visual connections between all elements.

Multiple inputs

Create multi-field forms with space efficiency by combining multiple inputs in a single input group. This approach works well for related fields like first/last name or city/state/zip.

@
HTML
<div class="input-group mb-medium" role="group" aria-labelledby="nameAddon">
  <label class="input-addon" id="nameAddon" for="multiInputFirstName">Name</label>
  <input type="text" class="form-input" id="multiInputFirstName" placeholder="First" aria-label="First name">
  <input type="text" class="form-input" placeholder="Last" aria-label="Last name">
</div>

<div class="input-group" role="group" aria-label="Email address">
  <input type="text" class="form-input" placeholder="Username" aria-label="Username">
  <span class="input-addon">@</span>
  <input type="text" class="form-input" placeholder="Domain" aria-label="Domain">
</div>

While multiple inputs are supported visually, note that validation states work best with single-input groups. For complex validated forms, consider using separate input groups with grid layout and placing validation feedback outside each group.

Sizing system

Chassis CSS's input groups include a unified sizing system that allows you to change the dimensions of all elements together by applying a single class to the container.

Small
Default
Large
HTML
<div class="input-group small mb-medium">
  <span class="input-addon">Small</span>
  <input type="text" class="form-input" aria-label="Small input group example">
</div>

<div class="input-group mb-medium">
  <span class="input-addon">Default</span>
  <input type="text" class="form-input" aria-label="Default input group example">
</div>

<div class="input-group large">
  <span class="input-addon">Large</span>
  <input type="text" class="form-input" aria-label="Large input group example">
</div>

The sizing system works by extending Chassis CSS's form size placeholders (%form-size-small, %form-size-medium, %form-size-large) to all elements within the input group, ensuring consistent proportions regardless of content.

Component integration

Chassis CSS's input groups seamlessly integrate with other form components to create powerful, specialized control interfaces.

With select menus

Combine input groups with select menus to create unified selection interfaces with context or additional options.

HTML
<div class="input-group mb-medium">
  <label class="input-addon" for="inputGroupSelect01">Category</label>
  <select class="form-input" id="inputGroupSelect01">
    <option selected>Choose...</option>
    <option value="1">Products</option>
    <option value="2">Services</option>
    <option value="3">Resources</option>
  </select>
</div>

<div class="input-group" role="group" aria-label="Price with currency">
  <select class="form-input" id="inputGroupSelect02" aria-label="Currency selection">
    <option value="usd" selected>USD</option>
    <option value="eur">EUR</option>
    <option value="gbp">GBP</option>
  </select>
  <input type="text" class="form-input" aria-label="Amount">
</div>

Select menus in input groups maintain their dropdown functionality and styling while visually integrating with the other elements. This creates compact, powerful controls for complex data entry tasks.

With file inputs

Enhance file inputs with contextual labels, instructions, or action buttons to create more user-friendly upload interfaces.

HTML
<div class="input-group mb-medium">
  <label class="input-addon" for="inputGroupFile01">Upload</label>
  <input type="file" class="form-input" id="inputGroupFile01">
</div>

<div class="input-group">
  <input type="file" class="form-input" id="inputGroupFile02" aria-label="File browser">
  <button class="button primary" type="button">Upload</button>
</div>

File inputs with addons create clear upload interfaces while maintaining browser-specific file selection behaviors. The combination helps users understand both the purpose and action associated with the control.

With dropdowns

Create rich, contextual inputs by combining input groups with Chassis CSS's dropdown component for additional options or actions.

HTML
<div class="input-group">
  <button class="button outline secondary menu-toggle" type="button" data-cx-toggle="menu" aria-expanded="false">Options</button>
  <ul class="menu">
    <li><a class="menu-item" href="#">Action</a></li>
    <li><a class="menu-item" href="#">Another action</a></li>
    <li><a class="menu-item" href="#">Something else</a></li>
  </ul>
  <input type="text" class="form-input" aria-label="Text input with dropdown">
</div>

Dropdowns within input groups maintain proper z-indexing to ensure menus appear above other form elements. The border radius is automatically managed to create a seamless visual connection.

Vertical groups

Stack multiple inputs and addons vertically to create multi-line forms with a compact footprint. This is ideal for address forms, multi-part data entry, or grouped settings.

HTML
<div class="input-group vertical" role="group" aria-label="Sign-in credentials">
  <input type="text" class="form-input" placeholder="Username" aria-label="Username">
  <input type="password" autocomplete="current-password" class="form-input" placeholder="Password" aria-label="Password">
</div>

Nested groups

Create complex, multi-field forms by nesting input groups within vertical groups. This allows you to maintain consistent styling and spacing while organizing related fields together.

HTML
<div class="input-group vertical" role="group" aria-labelledby="addressAddon">
  <label class="input-addon" for="inputAddressLine" id="addressAddon">Address</label>
  <input type="text" class="form-input" id="inputAddressLine" placeholder="123 Main St" aria-label="Street address">
  <div class="input-group" role="group" aria-label="City, state, and zip">
    <input type="text" class="form-input" placeholder="City" aria-label="City">
    <select class="form-input" aria-label="State">
      <option value="" selected>State</option>
      <option>State option</option>
    </select>
    <input type="text" class="form-input" placeholder="Zip" aria-label="Zip code">
  </div>
</div>

Accessibility

Input groups combine multiple elements visually, so explicit labeling is essential for assistive technology users.

Single-input groups

Use a <label> with a for attribute pointing to the input's id. The label can be a standalone .form-label before the group, or a .input-addon element inside it. If no visible label is needed, add aria-label directly to the input.

Multi-input groups

When a group contains more than one input, add role="group" to the .input-group element so the inputs are announced as a related set. Provide a group name with either aria-labelledby referencing the id of an addon that serves as the visible group label, or aria-label when no addon is suitable. Each individual input still needs its own aria-label.

Help text and validation

Place help text and validation feedback as siblings after .input-group, not inside it. Use aria-describedby on the associated input to link the two.

Interactive addons

All button addons must have an accessible name. Use visible text or aria-label for icon-only buttons.

Technical implementation

Chassis CSS's input group system is built on a combination of flexbox layout, CSS variables, and placeholder selectors to create a flexible yet consistent component.

Input groups utilize several key techniques:

  • Flexbox layout handles the alignment and spacing of elements
  • Border radius management uses targeted selectors to create seamless connections
  • Z-index layering ensures proper visual stacking during interactions
  • CSS variables enable theming and runtime customization
  • Sass placeholders maintain consistent sizing across element types

CSS

The Input group component can be customized at both runtime (via custom properties) and compile time (via Sass variables).

Custom properties

The Input group component exposes CSS custom properties to control its appearance at runtime.

scss/placeholders/_form.scss
--input-addon-fg-color: #{$input-addon-fg-color};
--input-addon-bg-image: #{$input-addon-bg-image};
--input-addon-bg-color: #{$input-addon-bg-color};
--input-addon-border-color: #{$input-addon-border-color};

Check the overview page to see the CSS variables shared by all form elements.

Sass variables

The Input group component uses Sass variables in scss/config/_defaults.scss to define its defaults.

scss/config/_defaults.scss
$input-addon-fg-color:                   $form-idle-fg-active;
$input-addon-bg-image:                   linear-gradient(var(--default-dim-slight), var(--default-dim-slight));
$input-addon-bg-color:                   $form-idle-bg-regular;
$input-addon-border-color:               $form-idle-border-color;

Check the overview page to see the Sass variables shared by all form elements.

Design tokens

Check the overview page to see the design tokens shared by all form elements.