# Input

Page: /docs/components/input

{/* Figma: Meridian → Input (docs 30:20, component set 20:4889). Spec: docs/design-system/meridian/input.md */}

A single-line field with its label, description and error built in. One size, 40 high with a 16 value and a 14 label, the same height as an xl Button. Every HubSpot form on the site is built from it; search, number and email are ways of setting it up, not separate parts.

```tsx
import { Input } from "@commenda/meridian/ui/input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

export function InputField() {
	return (
		<Fields>
			<Input label="Company name" placeholder="e.g. Northwind Ltd" />
			<Input
				label="Company name"
				defaultValue="Northwind Ltd"
				description="The legal name on your registration."
			/>
		</Fields>
	);
}
```

## Usage [#usage]

```tsx
import { Input } from "@commenda/meridian/ui/input";

<Input label="Company name" placeholder="e.g. Northwind Ltd" />;
```

## Field [#field]

Label above, value inside, one line of description below when it helps.

```tsx
import { Input } from "@commenda/meridian/ui/input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

export function InputField() {
	return (
		<Fields>
			<Input label="Company name" placeholder="e.g. Northwind Ltd" />
			<Input
				label="Company name"
				defaultValue="Northwind Ltd"
				description="The legal name on your registration."
			/>
		</Fields>
	);
}
```

## Label options [#label-options]

Required adds a red asterisk, optional says so in words, help opens a tooltip. Use one, not all three.

```tsx
import { Input } from "@commenda/meridian/ui/input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

export function InputLabelOptions() {
	return (
		<Fields cols={3}>
			<Input label="Work email" type="email" required defaultValue="maya@northwind.com" />
			<Input
				label="Phone extension"
				labelConfig={{ optionalLabel: "(optional)" }}
				placeholder="e.g. 204"
			/>
			<Input
				label="Annual revenue"
				labelConfig={{ help: "Last full financial year, in US dollars." }}
				prefix="$"
				defaultValue="2,400,000"
			/>
		</Fields>
	);
}
```

## Prefix and suffix [#prefix-and-suffix]

Units and fixed parts sit in tinted segments, never in the value.

```tsx
import { Input } from "@commenda/meridian/ui/input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

export function InputPrefixSuffix() {
	return (
		<Fields cols={3}>
			<Input label="Annual revenue" prefix="$" placeholder="e.g. 2,400,000" />
			<Input label="Company website" prefix="https://" placeholder="northwind.com" />
			<Input label="Share of sales abroad" suffix="%" defaultValue="35" />
		</Fields>
	);
}
```

## Icon and action [#icon-and-action]

A left icon for search. Actions sit in a segment at the end, like copy. Copy stays live when the field is disabled.

```tsx
import { Input } from "@commenda/meridian/ui/input";
import { SearchMdIcon } from "@commenda/pathfinder/icons/SearchMdIcon";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

export function InputIconAction() {
	return (
		<Fields>
			<Input
				label="Search guides"
				type="search"
				leadingIcon={<SearchMdIcon />}
				defaultValue="Sales tax nexus"
				actionConfig={{ kind: "clear" }}
			/>
			<Input
				label="Referral code"
				defaultValue="NW-2026-0412"
				disableConfig={{ isDisabled: true }}
				actionConfig={{ kind: "copy" }}
			/>
		</Fields>
	);
}
```

## States [#states]

Hover from the pointer. Focus is a blue border with a soft glow. Invalid shows the error in place of the description, after the person leaves the field.

```tsx
import { Input } from "@commenda/meridian/ui/input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

/** A form demo with its state name above it, full width so the field keeps its size. */
function Captioned({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex min-w-0 flex-col gap-2">
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
			{children}
		</div>
	);
}

export function InputStates() {
	return (
		<Fields cols={3}>
			<Captioned label="default">
				<Input label="Company name" placeholder="e.g. Northwind Ltd" />
			</Captioned>
			<Captioned label="filled">
				<Input label="Company name" defaultValue="Northwind Ltd" />
			</Captioned>
			<Captioned label="disabled">
				<Input
					label="Company name"
					defaultValue="Northwind Ltd"
					disableConfig={{ isDisabled: true }}
				/>
			</Captioned>
			<Captioned label="read-only">
				<Input label="Company name" defaultValue="Northwind Ltd" readOnly />
			</Captioned>
			<Captioned label="invalid">
				<Input
					label="Company name"
					defaultValue="Northwind"
					errorConfig={{ message: "Enter your company’s legal name.", reveal: "immediate" }}
				/>
			</Captioned>
		</Fields>
	);
}
```

## Anatomy [#anatomy]

Label row, field, then description or error. The field holds the optional prefix, left icon, value, suffix and action, in that order.

| Part | Value |
| --- | --- |
| Field | 40 (`control/xl`), radius 8, 1px soft-pearl 400 |
| Label | Label/14 Strong, soft-pearl 900 |
| Value | Label/16, soft-pearl 1000; placeholder soft-pearl 700 |
| Description, error | Label/14 |
| Focus | blue 700 border with a blue 200 glow |

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (conditional) | `string` |  |
| `hideLabel` | `boolean` |  |
| `aria-label` (conditional) | `string` |  |
| `required` (conditional) | `true \| false` |  |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` |  |
| `sourceConfig` | `FieldSourceConfig` |  |
| `description` | `string` |  |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` |  |
| `disableConfig` | `DisableConfig` |  |
| `value` (conditional) | `string` |  |
| `onValueChange` (conditional) | `(value: string) => void` |  |
| `defaultValue` | `string` |  |
| `prefix` | `string` |  |
| `leadingIcon` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |
| `suffix` | `string` |  |
| `type` (conditional) | `"password" \| "number" \| "search" \| "text" \| "email" \| "url" \| "tel"` |  |
| `actionConfig` | `FieldActionConfig \| CopyAction \| { kind: "clear"; label?: string; }` |  |

**`labelConfig` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `optionalLabel` (required) | `string` |  |

Do not supply: `help`.

**`labelConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `help` (required) | `string` |  |

Do not supply: `optionalLabel`.

**`sourceConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"entity" \| "record" \| "document"` |  |
| `label` (required) | `string` |  |
| `preview` (required) | `ReactNode` |  |
| `onOpen` (required) | `() => void` |  |
| `side` | `"top" \| "bottom"` |  |

**`errorConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `message` (required) | `string` |  |
| `reveal` | `"after-blur" \| "immediate"` |  |

**`disableConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isDisabled` (required) | `boolean` |  |
| `reason` | `string` |  |

**`actionConfig` fields, option 1 of 3**

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"copy"` |  |
| `label` | `string` |  |
| `onCopy` | `() => void` |  |
| `onCopyError` | `(error: Error) => void` |  |

**`actionConfig` fields, option 2 of 3**

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"clear"` |  |
| `label` | `string` |  |

**`actionConfig` fields, option 3 of 3**

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"reveal"` |  |
| `label` | `string` |  |
| `hideLabel` | `string` |  |

## Best practices [#best-practices]

- Labels are nouns in sentence case: Work email, Company name. Always show the label; the placeholder is never the only label.
- Placeholders are examples that start with "e.g.", or nothing. Never the label again, never an instruction.
- Descriptions say why we ask, in one line. On a demo form, ask only what sales needs.
- Errors say what happened and how to fix it ("Enter a work email, like name@company.com"), and appear only after the person leaves the field.
- Units go in a prefix or suffix, never in the value. Copy and clear are actions, never suffixes.
- A field next to a button is 40, the same as an xl Button. Focus is always visible: the blue border and glow.
- Source: Pathfinder Input. Meridian makes the field 40 tall with a 16 value, a 14 label and 14 help and error text.
