# nord-input-group > Input Group composes exactly one Nord Input or Textarea with reusable add-ons > while leaving the editable control, form state, and all consumer nodes owned > by the consumer. ## Usage Input Group presents exactly one [Input](/components/input/) or [Textarea](/components/textarea/) and one or more add-ons as a single field surface. The original control remains the sole editable, form-associated element; the group does not clone, move, or replace consumer content. **Supported controls:** the editable child must be exactly one direct `nord-input` or `nord-textarea`. Native inputs and arbitrary custom/third-party controls are unsupported because they cannot consume the group’s Field, validation, focus, and presentation contexts; unsupported compositions render the diagnostic fallback. > **Do:** - Use add-ons for short context such as units, URL prefixes, icons, keyboard hints, loading state, or a closely related action. - Provide exactly one direct `nord-input` or `nord-textarea` child and give the group a label, or compose it inside a [Field](/components/field/). - Use logical `inline-start`, `inline-end`, `block-start`, and `block-end` positions so the layout adapts to right-to-left languages. - Keep interactive add-ons explicitly enabled or disabled according to their own action state. > **Don't:** - Don’t put multiple editable controls in one group; use a Field Group for multiple fields. - Don’t use an add-on for lengthy help or validation copy; use a hint, Field Description, or Field Error. - Don’t visually reorder interactive add-ons with custom CSS, because keyboard order follows source order. - Don’t substitute a third-party input element. Input Group supports Nord Input and Textarea so it can preserve their established form, validation, and accessibility behavior. ## Add-on positions `nord-input-group-addon` defaults to `position="inline-start"`. Inline positions sit before or after the text control in the current writing direction. Block positions span the group above or below the control. Position is independent of source order, but focus and assistive-technology order still follow the DOM, so place interactive content in the order users should encounter it. The group shell supplies the one shared background and outline. Add-ons and the nested text control are transparent within that surface and do not draw internal divider borders. At the default medium size, inline add-ons keep the normal `--n-space-s` outer inset but remove padding at the control seam; the grouped control contributes one `--n-space-xs` gap on that side. A direct, standalone Icon gets a small token-derived optical adjustment automatically. An exact direct Button or Dropdown whose own size matches the group supplies its own control padding, so the add-on removes the duplicate wrapper padding; intentionally smaller nested controls retain the normal inset. Private Nord-token roles scale add-on typography, child gap, padding, seam gap, and target height with group `size`, while block add-ons share the native control's effective text inset. Clicking noninteractive add-on content focuses the text control. Buttons, links, dropdown triggers, and other interactive descendants keep their own pointer and keyboard behavior; Input Group neither synthesizes a control click nor disables those actions implicitly. ## Label ownership Input Group supports two label owners. Choose one pattern for each group; do not provide field copy in both places. ### Standalone Input Group Use the group’s `label` when Input Group stands on its own. Put `hint`, `error`, `required`, `invalid`, `disabled`, and `readonly` on the group when they describe the combined control. Input Group renders that field UI once and supplies its accessible name and description to the nested Shadow DOM control. Hint text appears above the shared surface by default. Add `hint-below` when the helper copy should follow the control. If an error is also present, the error appears first and the hint follows it, matching Input and Textarea. ```html https:// ``` ### Input Group inside Field Use [Field](/components/field/) when the surrounding form should own the label, description, error, disabled state, or invalid state. Do not also set `label`, `hint`, `error`, or `invalid` on Input Group. Field is the sole visible and accessible field owner; the group continues to own the combined surface. Put `required` on the direct Input or Textarea so Field Label can reflect it. A control may still own control-specific properties such as `name`, `value`, `autocomplete`, `readonly`, and native validation constraints. ```html Website https:// Enter the public address. This address is unavailable. ``` The nested Input or Textarea’s built-in label, hint, and error UI is suppressed while Field or standalone Input Group owns that field context. Keep this copy on the selected owner so users receive one label and one description. ## Field state Disabled state is an OR-merge of Field, Input Group, and the direct Input or Textarea: any one can disable the editable control. A `required` group or direct control publishes required state to the Field Label. Readonly state likewise comes from either the group or direct control. The nested Input or Textarea keeps its value, name, autocomplete, validation, native `input` and `change` events, focus methods, and form participation. Form reset restores its initial value, disabled controls are omitted from `FormData`, and readonly values remain submitted. ## Size Set group `size` to `s`, `m` (default), or `l`. The group owns the effective presentation of its direct Input or Textarea and add-ons so typography, line height, spacing, and block size stay aligned. A child’s own public `size` value is not mutated: group size takes presentation precedence only while the child is composed, and the child’s explicit size resumes if it moves outside. ## Custom presentation Use the group’s public CSS custom properties to adapt a supported Nord control rather than replacing it: - `--n-input-group-inline-size` - `--n-input-group-background` - `--n-input-group-background-inactive` - `--n-input-group-border-color` - `--n-input-group-border-radius` - `--n-input-group-target-size` (overrides the effective size’s token-derived target height) The Custom Input example customizes the supported Nord Input with its public properties and these variables; it does not accept a different control implementation. The exact-one-Nord-control boundary is intentional: it avoids forking form association, password-manager behavior, native events, and validation semantics. ## Accessibility - Every group needs an accessible label. Use the group’s `label`/label slot when standalone, or a connected Field Label inside Field. - Decorative icons should have no label. Give icon-only add-on buttons their own accessible label and associate a Tooltip when the action benefits from visible explanation. - Keep spinners labeled when they communicate meaningful asynchronous state. - Required, invalid, disabled, and readonly visuals mirror the effective native and ARIA state of the nested control. - Focus-visible styling follows keyboard focus on the text control, while `:focus-within` keeps the shared surface coherent as focus moves to add-on actions. - Logical layout, token-based colors, forced-colors support, reduced motion, multiline growth, and compact-width constraints are built into the group shell. ## Rendering boundary Input Group and Input Group Addon are scoped Light DOM shells. Input and Textarea retain their existing Shadow DOM. Only component-owned label, hint, error, and shell nodes receive the private scope stamp; consumer controls, add-on children, state, listeners, text, and DOM identity remain untouched. ## Examples ### Overview ```html ``` ### Label Ownership ```html
Standalone Input Group https:// Inside Field Website https:// Enter the public address.
``` ### Hint Below ```html @example.com ``` ### Inline Start ```html https:// ``` ### Inline End ```html .com ``` ### Block Start ```html https://example.com/users/ ``` ### Block End ```html Public profile name 14 / 30 ``` ### Icon ```html ``` ### Text ```html $ USD @example.com ``` ### Sizes ```html
Small (s) $ USD Org Nordhealth Personal ⌘K Markdown Draft 0 / 500 Saved Medium (m) $ USD Org Nordhealth Personal ⌘K Markdown Draft 0 / 500 Saved Large (l) $ USD Org Nordhealth Personal ⌘K Markdown Draft 0 / 500 Saved
``` ### Button ```html Copy API token ``` ### Kbd ```html ⌘ K ``` ### Dropdown ```html Organization Nordhealth Personal ``` ### Spinner ```html Saving… ``` ### Textarea ```html Markdown supported 0 / 500 characters ``` ### Custom Input ```html Last 30 days ``` ### R T L ```html ⌘ K 0 / 500 ``` ### Validation ```html Domain https:// .com Enter the complete public domain. This domain is already in use. ``` ### Disabled ```html ``` ## API Reference ### Properties - **size** (`'s' | 'm' | 'l'`, default: `'m'`) — Controls the effective size of the grouped Input or Textarea and add-ons. - **label** (`string`, default: `''`) — Plain-text label used when the group is not inside a Nord Field. - **hint** (`string | undefined`) — Optional standalone hint text. - **hint-below** (`boolean`, default: `false`) — Places the standalone hint below the group surface. - **error** (`string | undefined`) — Optional standalone error text. Supplying it makes the group invalid. - **required** (`boolean`, default: `false`) — Makes the grouped text control required. - **hide-label** (`boolean`, default: `false`) — Visually hides the standalone label while preserving its accessible name. - **hide-required** (`boolean`, default: `false`) — Hides the visual required indicator without changing native required state. - **invalid** (`boolean`, default: `false`) — Applies invalid state when the group is standalone. - **disabled** (`boolean`, default: `false`) — Disables the grouped text control without implicitly disabling add-on actions. - **readonly** (`boolean`, default: `false`) — Makes the grouped text control readonly. ### Slots - **(default)** — A single nord-input or nord-textarea plus Input Group Addons. - **label** — Optional rich label content for a standalone group. - **hint** — Optional rich hint content for a standalone group. - **error** — Optional rich validation message for a standalone group. ### CSS Custom Properties - `--n-input-group-inline-size` (default: `100%`) — Controls the group's inline size. - `--n-input-group-background` (default: `var(--n-color-surface)`) — Controls the shared control surface. - `--n-input-group-background-inactive` (default: `var(--n-color-active)`) — Controls the disabled and readonly surface. - `--n-input-group-border-color` (default: `var(--n-color-border-strong)`) — Controls the shared border colour. - `--n-input-group-border-radius` (default: `var(--n-border-radius-s)`) — Controls the shared corner radius. - `--n-input-group-target-size` — Overrides the size-derived compound control minimum block size. ### Dependencies - `field`