--- package: "@svenskaspel/ui" version: "4.4.0" document_type: "component-documentation" source: "@svenskaspel/ui/docs/button.md" canonical_url: "/components/button" usage_source: "src/app/(docs)/components/button/page.mdx" --- # Button Button is a clickable element that triggers events or actions. Buttons communicate actions and allow users to interact with interfaces in a variety of ways. ![Button](/images/components/button/button-figma-248dc.webp) *** ## Usage Buttons inform the users of possible actions they can take. Buttons can be used throughout the user interface, for example in: forms, cards, games, widgets and toolbars. ### Emphasis When designing consider the hierarchy between the available actions of your interface. The primary action of the screen should be represented by a primary button, while secondary and tertiary actions should be represented by lower emphasis buttons. ![Emphasis](/images/components/button/button-figma-9ecf2.webp) ### Button types ![Button types](/images/components/button/button-figma-08c62.webp) 1. Primary button 2. Secondary button 3. Outline button 4. Ghost button 5. Link button 6. Destructive #### Primary ![Primary – 1](/images/components/button/button-figma-87d36.webp) The primary button has the highest visual emphasis and should be reserved for highlighting primary action of the section or page. Generally, only one primary button should be presented at one time. Typical actions where a primary button should be used are making a purchase or completing a form. #### Secondary ![Secondary](/images/components/button/button-figma-87590.webp) Secondary buttons are less emphasized than the primary button. Secondary buttons should be used when an alternative, but related action to the primary is available, e.g. “cancel” or “back”. #### Outline ![Outline – 1](/images/components/button/button-figma-fd8ef.webp) Outline buttons are further visually de-emphasized and can be used for important, but non-primary actions. Typical usage can be accessing optional functions without committing to a confirming or cancelling action. #### Ghost ![Ghost](/images/components/button/button-figma-04cd7.webp) The ghost button is the lowest emphasis button and can be used for subtle actions in a design to provide the contextually least important option. Ghost buttons are often used together with a primary button. #### Link ![Link – 1](/images/components/button/button-figma-40df6.webp) Link buttons visually mimic text links in the interface and can be used to lead the user to other destinations where additional information or other functions are provided. Common uses for a link button are “learn more” and “terms and conditions” type actions. #### Destructive ![Destructive](/images/components/button/button-figma-c1103.webp) For actions that remove or delete data the destructive button can be used. In our customer facing interface few such actions are available, and as such should be used sparingly. However, scenarios where appropriate usage of the destructive type may be found more commonly in for example internal systems and applications. *** ## Formatting ### Button sizes Sizes outside of the default, medium option are available, but keep in mind to primarily utilize the different button types to establish hierarchy, and as such avoid grouping buttons of different size together. #### Small ![Button sizes – 1](/images/components/button/button-figma-78c82.webp) In designs where space is severely limited a small button may be used. In general try to use the medium size whenever possible. #### Medium ![Button sizes – 2](/images/components/button/button-figma-9721c.webp) The medium-sized button serves as the default option and is designed to accommodate the vast majority of use cases. #### Large and XLarge ![Button sizes – 3](/images/components/button/button-figma-6ba65.webp) The larger variant buttons can be used where the associated action demands extra attention, but should be done sparingly. A typical example may be a CTA within a hero banner at larger breakpoints, where a default size button may not be visually prominent enough. ### Anatomy Buttons contain one required element and, at least, one optional element. ![Anatomy](/images/components/button/button-figma-02956.webp) 1. Icon 2. Label 3. Container ### Text labels To assure good legibility, a text label should be placed on one line and not be wrapped on multiple lines. If you have narrowed width space to place your button, move it below the associated content. ![Text labels – 1](/images/components/button/button-figma-d1542.webp) > **Do:** Limit label text to one line within the button. ![Text labels – 2](/images/components/button/button-figma-9f7e9.webp) > **Don't:** Avoid having the label text span across two lines. *** ## Modify ### Icons Icons can be placed in a button to guide the user and to enhance the experience. The icon can be placed to the left, or to the right of the text. ![Icons](/images/components/button/button-figma-e1300.webp) 1. Icon left 2. Icon right ### Best practices for icons within buttons To make a button clear and intutive, only use one icon per button. If an icon is used in combination with a text label, align them horizontally. ![Best practices for icons within buttons – 1](/images/components/button/button-figma-b9f9e.webp) > **Do:** One icon per button ![Best practices for icons within buttons – 2](/images/components/button/button-figma-5a381.webp) > **Don't:** Limit icons to one per button ![Best practices for icons within buttons – 3](/images/components/button/button-figma-6ec4d.webp) > **Don't:** Don’t vertically align an icon and text in the center of a button. ### Icon button Icon buttons are compact buttons that only use an icon to represent the associated action, without a label. They can be used where space is limited or when the action can be clearly recognized solely by the icon. When using Icon buttons, be sure to use well-known standard symbols to avoid any ambiguity. ![Icon button](/images/components/button/button-figma-755b6.webp) A selection of Icon buttons: primary, secondary and ghost. Icon buttons are available in sizes medium (40 px), small (32 px) and extra small (24 px). The larger sizes (large and extra large) are not available to the Icon only option. ![Icon button](/images/components/button/button-figma-4cfac.webp) *** ## Behaviour ### Scaling and adaptation When designing, buttons (excluding icon only-buttons) may be extended to align to grid or fill a content area horizontally, or alternatively the width is determined by the contents of the button. #### Align to grid ![Scaling and adaptation – 1](/images/components/button/button-figma-563b9.webp) #### Hug content ![Scaling and adaptation – 2](/images/components/button/button-scaling-and-adaptation-2-4621-24244-1.webp) --- # Readme / API # Button and IconButton The `Button` and `IconButton` components provide versatile button functionalities. They are built using TypeScript, powered by Base UI's `useRender` hook, and styled using `class-variance-authority`. ## Importing ```typescript import { Button, IconButton } from '@svenskaspel/ui/react/button'; // Example icon import (ensure you have an icon component like this, e.g., from your icon library) import Checkmark from '@svenskaspel/ui/react/icons/Checkmark'; ``` ## Props Both `Button` and `IconButton` components accept all props that a standard HTML ` ``` The Button spinner is 16 × 16 px for `sm`, `md`, and `lg`, and 24 × 24 px for `xl`. IconButton uses a 16 × 16 px spinner in every size. Loading Button layout follows Figma: horizontal padding is 12/16/24/32 px for `sm`/`md`/`lg`/`xl`, with a 4 px icon gap for `sm` and 8 px otherwise. Heights remain 32/40/48/56 px. Link variants omit the padding and use heights 20/24/28/28 px. Loading IconButton links are 16 × 16 px in every size. ## Usage **Basic `Button`** ```typescript import * as React from "react"; import { Button } from '@svenskaspel/ui/react/button'; const MyComponent = () => { return ( ); }; export default MyComponent; ``` **`Button` with Icon and Text** You can include icons alongside text within a `Button`. The `gap-2` class for spacing between the icon and text is applied by default from the component's styles. ```typescript import * as React from "react"; import { Button } from '@svenskaspel/ui/react/button'; import Checkmark from '@svenskaspel/ui/react/icons/Checkmark'; // Example icon const MyComponent = () => { return ( ); }; export default MyComponent; ``` **`IconButton`** For buttons that are intended to only contain an icon, use the `IconButton` component as it has an even square shape. It requires a `label` prop for accessibility. ```typescript import * as React from "react"; import { IconButton } from '@svenskaspel/ui/react/button'; import Checkmark from '@svenskaspel/ui/react/icons/Checkmark'; // Example icon const MyComponent = () => { return ( ); }; export default MyComponent; ``` **Using the `render` Prop** The `render` prop (from Base UI's `useRender` hook) lets you swap the default ` ); }; export default MyComponent; ``` In this example, the `` tag receives the styling and accessibility props from the `Button` component, effectively making the link appear and function like a button with the "link" variant. This is particularly useful for semantic HTML when the action is navigational. The label ("Navigate") is passed as regular `children` — the swapped element is not required to be a single child of `Button` any more. ## Styling The `Button` and `IconButton` components use a utility function `cn` from `"@svenskaspel/ui/utils"` and style objects (`buttonVariants` for `Button`, `iconButtonVariants` for `IconButton`) to apply styles. These variants are defined using the `cva` (class-variance-authority) function. The cn function concatenates the variant classes with any additional `className` passed as a prop. ## Variants The `Button` component supports several variants: - `primary`: The main call-to-action button style. - `secondary`: A secondary action button style using primary-variant colors. - `neutral`: A neutral button style with neutral background. - `outline`: A button with a border and transparent background. - `ghost`: A button with transparent background, typically used for subtle actions. - `link`: A button styled to look like a hyperlink. - `destructive`: A button used for important/destructive actions that require special attention. You can specify the variant by passing the `variant` prop: `variant="primary"` ## Sizes The `size` prop determines the padding and font size of the buttons. **`Button` sizes** (Defined in `buttonVariants` from `styles.ts`) - `sm`: Small. - `md`: Medium. - `lg`: Large. - `xl`: Extra Large. **`IconButton` sizes** (Defined in `iconButtonVariants` from `styles.ts`) - `xs`: Extra Small. - `sm`: Small. - `md`: Medium. You can specify the size by passing the `size` prop: `size="md"` ### IconButton icon size IconButton uses a fixed 16 × 16 px SVG icon in every size and variant. The default button size is `md`. SVG dimensions are set by the shared `iconButtonVariants` styles, including SVGs nested inside an icon wrapper. | Size | Button width × height | Icon | | ---- | --------------------- | ---------- | | `xs` | 24 × 24 px | 16 × 16 px | | `sm` | 32 × 32 px | 16 × 16 px | | `md` | 40 × 40 px | 16 × 16 px |