> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Helper text

> Supplementary text below a form field that provides guidance, constraints, or feedback. Always tied to a specific field — it's not a general annotation element.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-helper-text--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--basic" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--basic&viewMode=story&globals=theme:light" title="Helper text basic story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* Format requirements the user needs before they start typing, e.g., "Password must be at least 8 characters".
* Validation feedback after a field has been interacted with, e.g., "Please enter a valid email address format (e.g., [name@example.com](mailto:name@example.com))."
* Contextual hints that reduce input errors, e.g., "Enter the 9 digit ID found in user settings."

## When not to use

* Long explanations — use a [Tooltip](/cdf/aura/primitives/toolip) or [Popover](/cdf/aura/primitives/popover) instead.
* Page-level or section-level guidance — use [Alert](/cdf/aura/primitives/alert) or plain text.

## Dos and don'ts

* **Do** show format hints upfront, not only after the user has already made a mistake.
* **Do** replace the default helper text with the error message when validation fails — don't stack both.
* **Do** keep it to one or two short sentences — if you need more than that, the field or the form design probably needs rethinking.
* **Do** ensure error messages say what's wrong and how to fix it, not just that something is wrong ("Enter a valid email address" not "Invalid input").
* **Don't** use it for information the user doesn't need to complete the field.
* **Don't** write helper text that just restates the label in different words.

## Often used with

Tied to a single field: always with that control's [Label](/cdf/aura/primitives/label) and one of [Input](/cdf/aura/primitives/input), [Textarea](/cdf/aura/primitives/textarea), [Select](/cdf/aura/primitives/select), [Combobox](/cdf/aura/primitives/combobox), [Checkbox](/cdf/aura/primitives/checkbox) / [Radio](/cdf/aura/primitives/radio) group, or [Switch](/cdf/aura/primitives/switch).

## Accessibility

* **Match input references:** Ensure every helper text `<span>` or `<p>` has a unique `id` matching its input's ARIA reference.
* **Preserve instruction context on error:** When an error appears, append the error element's `id` to `aria-describedby` or switch to `aria-errormessage` dynamically without removing the original instruction `id`.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### Size xs

Use the extra-small size for dense forms, compact tables, or inline field groups where vertical space is limited but guidance is still needed.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--size-xs" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--size-xs&viewMode=story&globals=theme:light" title="Helper text size xs story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Size sm

Use the small size as the default for most form fields—it balances readability with a compact footprint below standard inputs and selects.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--size-sm" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--size-sm&viewMode=story&globals=theme:light" title="Helper text size sm story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Error state

Show the error state after validation fails to explain what went wrong and how to fix it, replacing the default helper text rather than stacking both.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--error-state" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--error-state&viewMode=story&globals=theme:light" title="Helper text error state story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Success

Use the success state to confirm that a value passed validation—for example, after an async username check or password strength requirement is met.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--success" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--success&viewMode=story&globals=theme:light" title="Helper text success story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### With custom icon

Add a custom icon when the default state icons do not match your product vocabulary or when a specific metaphor helps users scan feedback faster.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--with-custom-icon" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--with-custom-icon&viewMode=story&globals=theme:light" title="Helper text with custom icon story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Warning

Use the warning state for values that are valid but may cause issues—such as a password that meets minimum requirements but is still weak.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--warning" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--warning&viewMode=story&globals=theme:light" title="Helper text warning story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Tip

Use the tip variant for optional guidance that helps users complete the field more efficiently without implying an error or success condition.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--tip" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--tip&viewMode=story&globals=theme:light" title="Helper text tip story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### No icon

Omit the icon when the message is neutral guidance and a leading glyph would add visual noise without aiding comprehension.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--no-icon" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--no-icon&viewMode=story&globals=theme:light" title="Helper text no icon story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Long text

Reserve longer helper text for constraints that truly need explanation; if copy grows beyond one or two sentences, reconsider the field design or link to a [Popover](/cdf/aura/primitives/popover).

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--long-text" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--long-text&viewMode=story&globals=theme:light" title="Helper text long text story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Size comparison

Compare sizes side by side when choosing typography for a form system so helper text stays visually aligned with its associated control.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--size-comparison" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--size-comparison&viewMode=story&globals=theme:light" title="Helper text size comparison story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### All states

Review all states together when auditing form feedback patterns to ensure consistent tone, color, and icon usage across your product.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-helper-text--all-states" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-helper-text--all-states&viewMode=story&globals=theme:light" title="Helper text all states story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>