# Button Group Helps you group multiple buttons together for a cohesive and organized layout. Ideal for presenting related actions or options side by side or vertically ## About The `ButtonGroup` component joins several `Button` components into one block. It takes care of the alignment, the spacing and the rounding of the outer edges, which is what you want for a toolbar, a set of view switches or a row of related actions. ## Example Import the Button component into your Svelte file. The following example shows how to use the button component! ```html Save Edit Delete ``` In this example, the `ButtonGroup` wraps multiple `Button` components, aligning them neatly in a single row. This structure is useful for presenting related actions in a visually consistent manner. ## Stacked Button The `ButtonGroup` component supports a stacked layout that arranges buttons vertically instead of side by side. This is helpful for mobile or narrow screens where space is limited. To use it, set the `stacked` prop to `true`. ```html ... ``` In this example the buttons stack one below the other. ## Outlined Button The `outline` prop in the `ButtonGroup` component gives all buttons a bordered look with a transparent background. It's useful when you want a lighter, less prominent style while keeping a consistent design. ```html ... ``` In this example, all buttons within the `ButtonGroup` have an outlined style, making them stand out with borders while keeping the background clear. ## Group Button Sizing The `size` prop in the `ButtonGroup` component sets the size of all buttons in the group, keeping them consistent. You can use predefined values like `'xs'`, `'sm'`, `'md'` (default), `'lg'`, `'xl'`, or `'auto'` to control the button dimensions. ```html ... ... ... ... ... ... ``` In this example the buttons are outlined, which is a lighter look than the filled default. ## Square Group Button The `ButtonGroup` component can stack buttons vertically instead of placing them side by side. This is useful for mobile or narrow screens. To enable it, set the `stacked` prop to `true`. ```html ... ``` In this example the buttons stack one below the other. ## Rounded Button Control The `rounded` prop controls the border-radius of the buttons within the `ButtonGroup`, allowing you to adjust the roundness of the button corners. You can choose from several options, such as `"sm"` for small rounded corners, `"md"` (default) for medium, `"lg"` for large, `"xl"` for extra-large, `"2xl"` for double extra-large, `"full"` for fully rounded corners, or `"none"` for no rounding at all. ```html ... ... ... ... ... ... ``` In this example, the buttons in the `ButtonGroup` have large rounded corners. The default value for the `rounded` prop is `"md"`, but you can customize it as per your design needs. ## Button Group Variants The `variant` prop in the `ButtonGroup` component allows you to choose between two button styles: `bordered` and `flat`. This prop customizes the visual separation between buttons in the group. - `flat` (default): the buttons sit flush against each other with no gap between them. - `bordered`: Adds borders between the buttons, giving each button a distinct outline. ```html ... ... ``` In the first example, the `bordered` variant adds visible borders between the buttons, while the second example uses the default `flat` variant for a smooth, border-less look. ## Button Group Color The `color` prop on the `ButtonGroup` sets the color for every button in the group. A single button can still override it with its own `color` prop. ```html Button 1 Button 2 Button 3 Button 4 Button 5 ``` In this example `size="lg"` applies to every button in the group. ## Button Group Theme The `theme` prop controls the overall theme of the buttons within the `ButtonGroup`. It allows you to choose from three options: `"default"`, `"soft"`, or `"gradient"`. Each theme applies a different visual style to the buttons to match your design preferences. ### Soft Theme The **soft theme** gives the buttons a softer and lighter appearance, making them more subtle and minimal. You can also use the color prop with the soft theme to further customize the button colors. ```html ... ... ``` ### Gradient Theme The **gradient theme** applies a gradient background to the buttons, giving them a vibrant and dynamic look. To customize the gradient's color scheme, use the `gradientColor` prop in combination with the gradient theme. ```html ... ... ``` ## Animation Speed The `animationSpeed` prop sets the transition speed (like the hover effect) for all buttons in the group. Available values are `"none"`, `"slower"`, `"slow"`, `"normal"` (default), `"fast"` and `"faster"`. A button can override it with its own `animationSpeed` prop. ```html Button 1 Button 2 Button 3 ``` ## Customization Use the `class` attribute to style the group container. To apply the same classes to every button in the group, use the `buttonClasses` prop. A button's own `class` attribute is applied after `buttonClasses`, so it can override them. ```html Save Edit Delete ``` ## Accessibility The `ButtonGroup` carries the roles and labels a screen reader needs, and every button inside it stays reachable by keyboard. ### ARIA Label The `ariaLabel` prop allows you to provide a custom label for the button group, enhancing its accessibility. The default value is "Button group". You can specify a more descriptive label depending on the context or functionality of the button group. ```html ... ``` The `role="group"` attribute is automatically included in the ButtonGroup component. This role helps assistive technologies understand that the buttons are part of a grouped set, improving the navigation and comprehension for users. ## Configuration ### Props | Name | Type | Default | Description | | --- | --- | --- | --- | | `stacked` | boolean | `false` | Determines if the buttons are stacked vertically. | | `outline` | boolean | `false` | Applies an outlined style to the button group. | | `size` | [BUTTON_SIZE](https://www.theui.dev/docs/types#button-size-type) | `md` | Specifies the size of the buttons in the group. | | `square` | boolean | `false` | Determines if the buttons in the group are square. | | `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `md` | Controls the rounded corners of the buttons in the group. | | `variant` | 'bordered' \| 'flat' | `flat` | Defines the visual style of the button group, either with borders between buttons or flat with no borders. | | `color` | 'brand' \| 'error' \| 'info' \| 'success' \| 'warning' | `brand` | Defines the color scheme of the button group. | | `theme` | 'default' \| 'soft' \| 'gradient' | `default` | Sets the overall theme of the button group, affecting colors and styles. | | `gradientColor` | 'brand' \| 'error' \| 'info' \| 'success' \| 'warning' | `brand` | Defines the base color of the gradient theme for the buttons in the group. | | `buttonClasses` | string | `` | Custom classes applied to every button in the group. A button's own `class` can override them. | | `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `normal` | Controls the animation speed for the button group. | | `ariaLabel` | string | `Button group` | Custom ARIA label for accessibility, describing the button group. | --- Category: Components Keywords: button-group, button, buttons, group, component, svelte, svelte-5, theui-svelte, component-library, ui, tailwindcss Full documentation set: https://www.theui.dev/llms-full.txt