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.
Button
v1.0.0 | View in Storybook- 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.
- 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. If you must use a disabled Button, include clarifying text or a tooltip to explain why.
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 Topbar 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 Modals, 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.Grouping
- Small groups (2-3): Use default size for small groups, with secondary or ghost buttons (plus one primary if needed). Use 8px spacing between buttons.
- Large groups (3+, e.g., toolbars): Use small ghost buttons to reduce visual clutter. Use 4px spacing between buttons.
Variants and when to use them
| 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 Dialogs or Action toolbars | 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
defaultbutton per view, if needed. If you have two, one of them is wrong. - 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
destructivebuttons inline as the first interaction.
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, or Tooltip that is exposed to assistive tech per implementation).