Input group

Groups labelled native controls with text, icons or buttons.

When to use

Use an input group when a field needs an attached unit, prefix or closely related action, such as search or password reveal. Keep the visible field label outside the group.

Search action

Use .input-group-text for a decorative icon or prefix and a native button for actions. Keep the label outside and hide decorative icons.

HTML
<label class="form-label" for="groupSearch">Search the documentation</label>
<div class="input-group">
	<span class="input-group-text" aria-hidden="true"><!-- Search icon --></span>
	<input class="form-control" id="groupSearch" name="search" type="search" />
	<button class="btn btn-primary btn-solid" type="button">Search</button>
</div>

Currency and unit suffixes

Add-ons are not labels. Preserve native attributes such as inputmode, min and step.

HTML
<label class="form-label" for="groupPrice">Price</label>
<div class="input-group">
	<span class="input-group-text" aria-hidden="true">€</span>
	<input class="form-control" id="groupPrice" name="price" inputmode="decimal" />
	<span class="input-group-text" aria-hidden="true">EUR</span>
</div>

Password reveal

Link the button with aria-controls and synchronize aria-pressed with the input type in application JavaScript.

HTML
<label class="form-label" for="groupPassword">Password</label>
<div class="input-group">
	<input
		class="form-control"
		id="groupPassword"
		name="password"
		type="password"
		autocomplete="current-password" />
	<button
		class="btn btn-primary btn-text"
		type="button"
		aria-controls="groupPassword"
		aria-pressed="false"
		aria-label="Show password">
		Show password
	</button>
</div>

Textarea and select

The group accepts textarea .form-control and native .form-select elements, wrapping when needed.

Sizes

Use .input-group-sm or .input-group-lg to size every item.

Invalid and disabled

Keep validation on the native control with .is-invalid, aria-invalid="true" and aria-describedby. Disable every control in a disabled group.

Enter an amount greater than zero.

Right to left

Logical spacing follows document direction without changing source order.

Accessibility and behavior

  • Keep the native input, textarea or select labelled. Add-ons explain a value but do not replace its label; connect meaningful hints through aria-describedby.
  • Use named native buttons for actions. A password reveal button should keep aria-pressed and the input type synchronized without clearing the value or losing focus.
  • Put validation state and error references on the control. Disable each interactive group member when the group is unavailable; a visual wrapper state is insufficient.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--input-group-bg-colorvar(--bg-surface)Background color..input-group
--input-group-border-widthvar(--border-width)Border thickness..input-group
--input-group-border-colorvar(--control-border-color)Border color..input-group
--input-group-border-radiusvar(--border-radius-lg)Corner radius..input-group
--input-group-box-shadownoneOuter shadow..input-group
--input-group-colorvar(--text-color)Text and icon color..input-group
--input-group-addon-bg-colorvar(--bg-highlight)Background of addon text..input-group
--input-group-addon-colorvar(--text-muted)Addon text color..input-group
--input-group-insetvar(--spacer-1)Space between the outer group border and its children..input-group
--input-group-gapvar(--spacer-1)Space between child elements..input-group
--input-group-item-border-radiuscalc(var(--input-group-border-radius) - var(--input-group-inset))Corner radius of inner controls, buttons and addons..input-group
--input-group-padding-yvar(--spacer-1)Top and bottom padding..input-group
--input-group-padding-xvar(--spacer-3)Left and right padding..input-group
--input-group-font-sizevar(--font-size)Text size..input-group
--input-group-control-min-size8remPreferred minimum width of a flexible control; capped by available space..input-group
--input-group-focus-border-colorvar(--primary-hover)Border color while focused..input-group (focus)
--input-group-focus-outline-widthvar(--focus-outline-width)Focus ring thickness..input-group (focus)
--input-group-focus-outline-stylevar(--focus-outline-style)Focus ring line style..input-group (focus)
--input-group-focus-outline-colorvar(--focus-outline-color)Focus ring color..input-group (focus)
--input-group-focus-outline-offsetvar(--focus-offset)Distance between the focus ring and control..input-group (focus)
--input-group-invalid-colorvar(--error)Accent color for invalid controls and feedback..input-group (invalid)
--input-group-disabled-text-colorvar(--disabled-text-color)Text color while disabled..input-group (disabled)
--input-group-disabled-bg-colorvar(--disabled-bg-color)Background color while disabled..input-group (disabled)
--input-group-disabled-border-colorvar(--disabled-border-color)Border color while disabled..input-group (disabled)
--input-group-transition-durationvar(--transition-duration)Duration of visual state transitions..input-group
--input-group-transition-easingvar(--transition-easing)Timing curve for visual state transitions..input-group