Button Group
A group of buttons displayed together with unified styling
Basic Button Groups
Simple button group with different variants
Default (Background Variant)
Ghost Variant
Code Svelte
1
2<script lang="ts">
3 import { Button, ButtonGroupPrimitives } from "@kareyes/aether";
4
5 const { ButtonGroup } = ButtonGroupPrimitives;
6</script>
7
8<div class="space-y-4">
9 <!-- Background Variant -->
10 <div>
11 <h3 class="text-lg font-medium mb-2">Default (Background Variant)</h3>
12 <ButtonGroup variant="bg">
13 <Button variant="outline">First</Button>
14 <Button variant="outline">Second</Button>
15 <Button variant="outline">Third</Button>
16 </ButtonGroup>
17 </div>
18
19 <!-- Ghost Variant -->
20 <div>
21 <h3 class="text-lg font-medium mb-2">Ghost Variant</h3>
22 <ButtonGroup variant="ghost">
23 <Button variant="ghost">Copy</Button>
24 <Button variant="ghost">Paste</Button>
25 <Button variant="ghost">Cut</Button>
26 </ButtonGroup>
27 </div>
28</div>With Text Labels
Button groups can include text labels for context
Toolbar with Label (Background)
Actions with Label (Ghost)
Code Svelte
1
2<script lang="ts">
3 import { Button, Badge, ButtonGroupPrimitives } from "@kareyes/aether";
4
5 const { ButtonGroup, ButtonGroupText } = ButtonGroupPrimitives;
6</script>
7
8<div class="space-y-4">
9 <!-- Toolbar with Label (Background) -->
10 <div>
11 <h3 class="text-lg font-medium mb-2">Toolbar with Label (Background)</h3>
12 <ButtonGroup variant="bg">
13 <ButtonGroupText variant="bg">
14 <Badge variant="secondary" size="sm">Tools</Badge>
15 </ButtonGroupText>
16 <Button variant="outline" size="sm">Settings</Button>
17 <Button variant="outline" size="sm">Analytics</Button>
18 <Button variant="outline" size="sm">Search</Button>
19 </ButtonGroup>
20 </div>
21
22 <!-- Actions with Label (Ghost) -->
23 <div>
24 <h3 class="text-lg font-medium mb-2">Actions with Label (Ghost)</h3>
25 <ButtonGroup variant="ghost">
26 <ButtonGroupText variant="ghost">Actions</ButtonGroupText>
27 <Button variant="ghost" size="sm">Save</Button>
28 <Button variant="ghost" size="sm">Export</Button>
29 <Button variant="ghost" size="sm">Share</Button>
30 </ButtonGroup>
31 </div>
32</div>With Separators
Use separators to group related actions
File Menu Style
Text Formatting Toolbar
Code Svelte
1
2<script lang="ts">
3 import { Button, ButtonGroupPrimitives } from "@kareyes/aether";
4
5 const { ButtonGroup, ButtonGroupText, ButtonGroupSeparator } = ButtonGroupPrimitives;
6</script>
7
8<div class="space-y-4">
9 <!-- File Menu Style -->
10 <div>
11 <h3 class="text-lg font-medium mb-2">File Menu Style</h3>
12 <ButtonGroup variant="bg">
13 <Button variant="outline">New</Button>
14 <Button variant="outline">Open</Button>
15 <ButtonGroupSeparator />
16 <Button variant="outline">Save</Button>
17 <Button variant="outline">Save As</Button>
18 <ButtonGroupSeparator />
19 <Button variant="outline">Print</Button>
20 </ButtonGroup>
21 </div>
22
23 <!-- Text Formatting Toolbar -->
24 <div>
25 <h3 class="text-lg font-medium mb-2">Text Formatting Toolbar</h3>
26 <ButtonGroup variant="bg">
27 <ButtonGroupText variant="bg">Format</ButtonGroupText>
28 <Button variant="outline" size="sm"><strong>B</strong></Button>
29 <Button variant="outline" size="sm"><em>I</em></Button>
30 <Button variant="outline" size="sm"><u>U</u></Button>
31 <ButtonGroupSeparator />
32 <Button variant="outline" size="sm">Left</Button>
33 <Button variant="outline" size="sm">Center</Button>
34 <Button variant="outline" size="sm">Right</Button>
35 </ButtonGroup>
36 </div>
37</div>Vertical Orientation
Button groups can be displayed vertically
Navigation Menu (Background)
Sidebar Actions (Ghost)
Code Svelte
1
2<script lang="ts">
3 import { Button, ButtonGroupPrimitives } from "@kareyes/aether";
4
5 const { ButtonGroup, ButtonGroupText } = ButtonGroupPrimitives;
6</script>
7
8<div class="flex gap-8">
9 <!-- Navigation Menu (Background) -->
10 <div>
11 <h3 class="text-lg font-medium mb-2">Navigation Menu (Background)</h3>
12 <ButtonGroup orientation="vertical" variant="bg">
13 <Button variant="outline">Dashboard</Button>
14 <Button variant="outline">Projects</Button>
15 <Button variant="outline">Tasks</Button>
16 <Button variant="outline">Settings</Button>
17 </ButtonGroup>
18 </div>
19
20 <!-- Sidebar Actions (Ghost) -->
21 <div>
22 <h3 class="text-lg font-medium mb-2">Sidebar Actions (Ghost)</h3>
23 <ButtonGroup orientation="vertical" variant="ghost">
24 <ButtonGroupText variant="ghost">Quick Actions</ButtonGroupText>
25 <Button variant="ghost">New Note</Button>
26 <Button variant="ghost">New Folder</Button>
27 <Button variant="ghost">Add Link</Button>
28 </ButtonGroup>
29 </div>
30</div>Complex Examples
Advanced button group configurations
Editor Toolbar
Media Player Controls
Status Actions
Code Svelte
1
2<script lang="ts">
3 import { Button, Badge, ButtonGroupPrimitives } from "@kareyes/aether";
4
5 const { ButtonGroup, ButtonGroupText, ButtonGroupSeparator } = ButtonGroupPrimitives;
6</script>
7
8<div class="space-y-4">
9 <!-- Editor Toolbar -->
10 <div>
11 <h3 class="text-lg font-medium mb-2">Editor Toolbar</h3>
12 <div class="flex flex-wrap gap-4">
13 <ButtonGroup variant="bg">
14 <ButtonGroupText variant="bg">File</ButtonGroupText>
15 <Button variant="outline" size="sm">New</Button>
16 <Button variant="outline" size="sm">Open</Button>
17 <Button variant="outline" size="sm">Save</Button>
18 </ButtonGroup>
19
20 <ButtonGroup variant="bg">
21 <ButtonGroupText variant="bg">Edit</ButtonGroupText>
22 <Button variant="outline" size="sm">Undo</Button>
23 <Button variant="outline" size="sm">Redo</Button>
24 <ButtonGroupSeparator />
25 <Button variant="outline" size="sm">Cut</Button>
26 <Button variant="outline" size="sm">Copy</Button>
27 <Button variant="outline" size="sm">Paste</Button>
28 </ButtonGroup>
29 </div>
30 </div>
31
32 <!-- Status Actions -->
33 <div>
34 <h3 class="text-lg font-medium mb-2">Status Actions</h3>
35 <ButtonGroup variant="bg">
36 <ButtonGroupText variant="bg">
37 <Badge variant="flat" color="green">Online</Badge>
38 </ButtonGroupText>
39 <Button variant="outline" size="sm">View Profile</Button>
40 <Button variant="outline" size="sm">Edit Status</Button>
41 <Button variant="outline" size="sm">Settings</Button>
42 </ButtonGroup>
43 </div>
44</div>Mixed Button Variants
Combine different button styles within a group
Call-to-Action Group
Form Actions
Code Svelte
1
2<script lang="ts">
3 import { Button, ButtonGroupPrimitives } from "@kareyes/aether";
4
5 const { ButtonGroup, ButtonGroupText } = ButtonGroupPrimitives;
6</script>
7
8<div class="space-y-4">
9 <!-- Call-to-Action Group -->
10 <div>
11 <h3 class="text-lg font-medium mb-2">Call-to-Action Group</h3>
12 <ButtonGroup variant="bg">
13 <Button variant="default">Get Started</Button>
14 <Button variant="outline">Learn More</Button>
15 <Button variant="ghost">Skip</Button>
16 </ButtonGroup>
17 </div>
18
19 <!-- Form Actions -->
20 <div>
21 <h3 class="text-lg font-medium mb-2">Form Actions</h3>
22 <ButtonGroup variant="bg">
23 <ButtonGroupText variant="bg">Actions</ButtonGroupText>
24 <Button variant="default">Submit</Button>
25 <Button variant="outline">Save Draft</Button>
26 <Button variant="ghost">Cancel</Button>
27 </ButtonGroup>
28 </div>
29</div>Features
- Variants: Multiple visual styles (bg, ghost)
- Orientations: Horizontal and vertical layouts
- Text Labels: Built-in support for group labels
- Separators: Visual separators between button groups
- Accessibility: Full keyboard navigation and screen reader support
- TypeScript: Complete type safety with exported types
Basic Button Group
<script>
import { ButtonGroup, Button } from "@kareyes/aether";
</script>
<ButtonGroup variant="bg">
<Button variant="outline">First</Button>
<Button variant="outline">Second</Button>
<Button variant="outline">Third</Button>
</ButtonGroup>
With Text Labels
<script>
import { ButtonGroup, ButtonGroupText, Button } from "@kareyes/aether";
</script>
<ButtonGroup variant="bg">
<ButtonGroupText variant="bg">Actions</ButtonGroupText>
<Button variant="outline">Save</Button>
<Button variant="outline">Delete</Button>
<Button variant="outline">Cancel</Button>
</ButtonGroup>
With Separators
<script>
import { ButtonGroup, ButtonGroupSeparator, Button } from "@kareyes/aether";
</script>
<ButtonGroup variant="bg">
<Button variant="outline">File</Button>
<ButtonGroupSeparator />
<Button variant="outline">Edit</Button>
<Button variant="outline">View</Button>
<ButtonGroupSeparator />
<Button variant="outline">Help</Button>
</ButtonGroup>
Vertical Orientation
<ButtonGroup orientation="vertical" variant="bg">
<Button variant="outline">Top</Button>
<Button variant="outline">Middle</Button>
<Button variant="outline">Bottom</Button>
</ButtonGroup>
Ghost Variant
<ButtonGroup variant="ghost">
<ButtonGroupText variant="ghost">Tools</ButtonGroupText>
<Button variant="ghost">Settings</Button>
<Button variant="ghost">Help</Button>
</ButtonGroup>
Components
ButtonGroup
The main container component that groups buttons together.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
variant |
"bg" | "ghost" |
"bg" |
Visual variant of the button group |
orientation |
"horizontal" | "vertical" |
"horizontal" |
Layout orientation |
class |
string |
undefined |
Additional CSS classes |
Data Attributes
data-slot="button-group"- Identifies the button group containerdata-orientation- Current orientation valuedata-variant- Current variant value
ButtonGroupText
A text label component that adapts its styling based on the group variant.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
variant |
"bg" | "ghost" |
"bg" |
Visual variant matching the button group |
class |
string |
undefined |
Additional CSS classes |
child |
Snippet |
undefined |
Custom render function |
ButtonGroupSeparator
A visual separator component for dividing button groups.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
orientation |
"vertical" | "horizontal" |
"vertical" |
Separator orientation |
class |
string |
undefined |
Additional CSS classes |
Variants
Background (bg)
- Default variant with background styling for text elements
- Provides clear visual grouping with borders and shadows
- Best for prominent toolbars and action groups
Ghost (ghost)
- Minimal variant with transparent background for text elements
- Subtle styling for secondary or inline actions
- Good for compact interfaces and sidebar navigation
Examples
Toolbar Example
<ButtonGroup variant="bg">
<ButtonGroupText variant="bg">Format</ButtonGroupText>
<Button variant="outline" size="sm">Bold</Button>
<Button variant="outline" size="sm">Italic</Button>
<ButtonGroupSeparator />
<Button variant="outline" size="sm">Left</Button>
<Button variant="outline" size="sm">Center</Button>
<Button variant="outline" size="sm">Right</Button>
</ButtonGroup>
Navigation Menu
<ButtonGroup orientation="vertical" variant="ghost">
<ButtonGroupText variant="ghost">Navigation</ButtonGroupText>
<Button variant="ghost">Dashboard</Button>
<Button variant="ghost">Projects</Button>
<Button variant="ghost">Settings</Button>
</ButtonGroup>
Mixed Button Variants
<ButtonGroup variant="bg">
<Button variant="default">Primary</Button>
<Button variant="outline">Secondary</Button>
<Button variant="ghost">Tertiary</Button>
</ButtonGroup>
Styling
The component uses Tailwind CSS and tailwind-variants for styling. You can customize the appearance by:
- CSS Variables: Modify design tokens in your CSS
- Class Overrides: Pass custom classes via the
classprop - Variant Customization: Extend the
buttonGroupVariantsconfiguration
CSS Variables
:root {
--border-input: /* border color for separators */
--background-muted: /* background for bg variant text */
--shadow-xs: /* shadow for bg variant text */
}
Accessibility
- Keyboard Navigation: Full keyboard support for all grouped elements
- Screen Readers: Proper ARIA roles and labels
- Focus Management: Visual focus indicators and logical tab order
- Semantic HTML: Uses appropriate HTML elements and structure
ARIA Attributes
role="group"- Applied to the button group container- Proper labeling for screen readers
- Focus management between grouped elements
TypeScript
import type {
ButtonGroupVariant,
ButtonGroupOrientation
} from "@kareyes/aether";
// Variant type
type Variant = ButtonGroupVariant; // "bg" | "ghost"
// Orientation type
type Orientation = ButtonGroupOrientation; // "horizontal" | "vertical"
Best Practices
- Group Related Actions: Only group buttons that are logically related
- Consistent Variants: Use the same variant for all elements in a group
- Appropriate Orientation: Use vertical for navigation, horizontal for actions
- Text Labels: Provide context with ButtonGroupText when needed
- Separators: Use separators to create logical sections within groups
- Accessibility: Always provide proper labels and keyboard navigation
Common Patterns
File Menu
<ButtonGroup variant="bg">
<ButtonGroupText variant="bg">File</ButtonGroupText>
<Button variant="outline">New</Button>
<Button variant="outline">Open</Button>
<ButtonGroupSeparator />
<Button variant="outline">Save</Button>
</ButtonGroup>
Status Bar
<ButtonGroup variant="ghost">
<ButtonGroupText variant="ghost">Status: Online</ButtonGroupText>
<Button variant="ghost" size="sm">Settings</Button>
</ButtonGroup>
Media Controls
<ButtonGroup variant="bg">
<Button variant="outline">⏮️</Button>
<Button variant="outline">⏯️</Button>
<Button variant="outline">⏭️</Button>
<ButtonGroupSeparator />
<Button variant="outline">🔊</Button>
</ButtonGroup>