> ## 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.

# Button

> Use a Button to communicate actions users can take and to allow users to interact with the page. Each page should have only one primary Button, and any remaining calls to action should be represented as lower-emphasis Buttons.

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

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

## Placement

* Buttons should be placed contextually near the objects they affect for easy discoverability.

### Right side

Buttons should always be placed furthest right in the following contexts:

* Full page: If the action affects the entire content on the page, Buttons should be placed either in the page header area on the right or within the Page toolbar with the Primary Button being furthest right.
* In side panels: Buttons can be placed in the header or footer area, with the Primary Button being furthest right.
* In Dialogs, steppers or wizards: Buttons always appear in the footer, with the Primary Button being furthest right.

### Left side

Buttons may make more sense to place on the left side in the following contexts:

* Cards: Card content is always left aligned and Buttons placed on the left to align with content makes for better readability.
* Lists: In dense lists when content is left aligned, it may make more sense to place relevant Buttons on the left to align with content.

### When to use a full width Button

Buttons by default have fixed paddings. The width of the Button adjusts to accommodate the label keeping the correct padding on all sides.
However, Buttons can span the full width of their parent container. Full width buttons help visually distinguish actions from other screen elements so they are easier to detect. The content of the Button always stays centered. Examples of when you might want to use a full width Button are in narrow side panels or small containers such as Popovers and Menus.

## Grouping

* Small groups (2-3): Use secondary and/or ghost buttons (plus one primary if needed) with 8px spacing between buttons.
* Large groups (3+, e.g., toolbars): Use mainly ghost buttons to reduce visual clutter with 8px spacing between buttons.

## Variants and when to use them

* Consider Button hierarchy: We use different Button types to establish a visual hierarchy. You don't always need to use the secondary Button as the second Button in your layout. The most important thing is to establish a visual hierarchy between the buttons in your UI, which is why only one primary Button should be used on a page.
* Type indicates importance: The Button type should be chosen based on the importance of the action. More important, more emphasis.
* Verb + noun format: Reference action label guidelines in the design.md file to use the appropriate verb. It's always best to use a label with your Button unless the icon is highly recognizable, such as the save (floppy disk) or delete (trash bin) icons, or space is limited. Alternatively, use an icon button with a [Tooltip](/cdf/aura/primitives/tooltip).
* Avoid disabled Buttons: Disabled Buttons can be confusing and frustrating for many users and can be difficult to spot for those with low vision or users relying on keyboard interactions, since disabled Buttons won't take keyboard focus. To make things easier, enable the Button so users can click it, and provide an error message or inline validation if information is incorrect or missing. Or try using alternative methods to activate a Button control such as selections that trigger an [Action toolbar](/cdf/aura/primitives/action-toolbar). If you must use a disabled Button, include clarifying text or a tooltip to explain why.

| Variant             | Use                                                                                                                                                                        | When NOT to use                                                             | Max number per context |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :--------------------- |
| `default` (primary) | The single most important action on a screen                                                                                                                               | Don't use more than once per view. Never for navigation.                    | 1                      |
| `secondary`         | Supporting actions that aren't the primary CTA                                                                                                                             | Don't use as a substitute for a primary button                              | A few                  |
| `outline`           | Low-emphasis actions in dense UI or to create contrast with background colors                                                                                              | Don't use as the primary action                                             | A few                  |
| `ghost`             | Tertiary actions, icon buttons in toolbars                                                                                                                                 | Don't use as a primary or secondary action                                  | As many as needed      |
| `destructive`       | Irreversible, high-consequence actions (delete, remove), most commonly in [Dialog](/cdf/aura/primitives/dialog)s or [Action toolbar](/cdf/aura/primitives/action-toolbar)s | Don't use for general negative actions — only for truly destructive commits | 1                      |
| `loading`           | Actions that are in progress                                                                                                                                               | Don't use for general page loading states                                   | 1 at a time            |

## Dos and don'ts

* **Do** use only one `default` (primary) button per view, if needed.
* **Do** use size="sm" for buttons in the Topbar action slot. Match this in your designs.
* **Don't** use a button where a link should be. Buttons change state or trigger actions. Links navigate.
* **Don't** use `destructive` buttons inline as the first interaction. Use a `ghost` or other Button type then use the `destructive` Button when the user confirms the action.

## Behavior

* Primary action submits or commits the labeled operation; support keyboard activation (Enter / Space) when the control is focusable.
* Loading state should prevent duplicate submissions where the action is not idempotent.
* Icon-only buttons must have an accessible name (visible label, [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label), or [Tooltip](/cdf/aura/primitives/tooltip) that is exposed to assistive tech per implementation).

## Toggle vs Button

A standard Button triggers a one time action and returns to its resting state immediately after, whereas a Toggle maintains an on/off state until clicked again. Toggled Buttons have different visual identities than Buttons and should be used to indicate the following interactions:

* A selected element such as in a Toolbar.
* An applied filter such as in Page toolbar.

## Often used with

[Tooltip](/cdf/aura/primitives/tooltip) on icon-only triggers; [Menu](/cdf/aura/primitives/dropdown-menu) (dropdown / split); [KBD](/cdf/aura/primitives/kbd) hints in labels; pairs with [Dialog](/cdf/aura/primitives/dialog), [Popover](/cdf/aura/primitives/popover), or [Action toolbar](/cdf/aura/primitives/action-toolbar) as trigger.

## 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.

### Default sizes

Use default (primary) Button sizes for the main call to action on a page or in a form footer; match size to surrounding UI density while keeping the primary action visually prominent.

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

### Secondary sizes

Use secondary Button sizes for supporting actions that are important but not the primary CTA—for example, "Cancel" beside "Save" in a dialog.

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

### Outline sizes

Use outline Button sizes for low-emphasis actions in dense interfaces or on varied backgrounds where a filled button would compete with the primary action.

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

### Ghost sizes

Use ghost Button sizes for tertiary actions and icon buttons in toolbars where minimal visual weight is needed to reduce clutter.

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

### On dark variants

Use on-dark Button variants when placing buttons on dark or tinted backgrounds such as banners, media overlays, or inverted header regions.

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

### Destructive sizes

Use destructive Button sizes for irreversible actions such as delete or remove, typically in dialogs or confirmation flows where the consequence is explicit.

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

### Button states

Reference Button states—default, hover, focus, active, and disabled—to ensure interactive feedback is clear and consistent across variants.

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

### All sizes

Compare all Button sizes to choose the scale appropriate for the context, from compact toolbars (`sm`) to prominent page-level actions (`default` or `lg`).

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

### With left icon

Place an icon to the left of the Button label when it reinforces the action meaning—for example, a plus icon before "Add item."

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

### With right icon

Place an icon to the right of the Button label when it indicates direction or outcome—for example, a chevron before "Next" or an external-link icon for opening in a new context.

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

### Icon buttons

Use icon-only Buttons when space is limited and the icon is widely recognized; always pair with a Tooltip or accessible name so the action is not ambiguous.

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

### Disabled

Avoid disabled Buttons when possible; if used, provide adjacent text or a Tooltip explaining why the action is unavailable so users are not left guessing.

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

### Loading

Use the loading Button state during in-progress operations to prevent duplicate submissions and signal that the action is being processed.

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

### In context

Review Buttons in context—alongside forms, cards, or toolbars—to validate hierarchy, spacing, and alignment with surrounding content.

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

### Click interaction

Verify Button click interaction fires the expected action once per activation and does not conflict with parent clickable regions.

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

### Keyboard navigation

Ensure Buttons are focusable and activatable with Enter and Space, and that focus order follows a logical path through grouped actions.

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

## Accessibility

* Icon-only buttons: Always provide an explicit `aria-label` or an internal screen-reader-only text element (`<span className="sr-only">`) when no visual text label exists.
* Disabled states: Use `aria-disabled="true"` rather than native HTML `disabled` attributes if you need the button to retain keyboard focusability (e.g., to trigger an explanatory disabled-state tooltip).

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

### Form button types

Use correct HTML button types in forms—`submit`, `reset`, or `button`—so Enter key behavior and form submission work as users expect.

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

### Edge case empty

Avoid rendering Buttons with empty labels; empty buttons fail accessibility checks and give users no indication of the action.

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

### Edge case long text

Test Buttons with long labels to ensure text wraps or truncates gracefully within width constraints without breaking layout.

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

### Edge case special characters

Verify Buttons render special characters and localized strings correctly in labels without clipping or encoding issues.

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

### Edge case multiple icons

Avoid multiple icons in a single Button unless the pattern is explicitly supported; extra icons often confuse the action meaning.

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

### Edge case whitespace

Trim whitespace in Button labels; leading or trailing spaces can cause misalignment and inconsistent sizing.

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

### Edge case nested elements

Keep Button content flat; nested interactive elements inside a Button break accessibility and click targeting.

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

### Edge case width constraints

Test Buttons in narrow containers to confirm labels truncate or wrap appropriately, or switch to icon-only with a Tooltip when space is critical.

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

### Edge case icon only

Icon-only Buttons must always include an accessible name via `aria-label` or Tooltip so screen reader users understand the action.

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

### Edge case rapid state changes

Handle rapid state changes—such as quick toggling between default and loading—so the Button does not flicker or allow duplicate submissions.

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

### Edge case invisible content

Ensure Button labels and icons are visible and meet contrast requirements; invisible or near-invisible content makes actions unusable for many users.

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