Overview
SplitButton combines a main action button with a settings dropdown. Settings are automatically persisted to localStorage, making user preferences sticky across sessions.
Key Features
- Main action button + dropdown settings menu
- Automatic localStorage persistence for all settings
- Dynamic button label and icon based on current settings
- Toast notifications on action success/error
- Support for multiple option groups in the dropdown
Examples
Export Format Selector
Common pattern: let users choose their preferred export format.
Download Options
Download with quality or format options.
Multiple Option Groups
Combine multiple settings in one dropdown.
Button Variants
SplitButton supports all standard button variants.
Default
Disabled
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
groups | SplitButtonGroup[] | required | Array of option groups with label, storageKey, defaultValue, and options |
onAction | (settings) => void | Promise | required | Async callback when main button is clicked, receives current settings |
getLabel | (settings) => string | - | Function to generate button label from current settings |
getIcon | (settings) => IconDefinition | - | Function to generate button icon from current settings |
successMessage | string | (settings) => string | "Action completed" | Function or string for success toast message |
disabled | boolean | false | Disables both the action button and settings dropdown |
SplitButtonGroup Interface
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | - | Group label shown in dropdown header |
storageKey | string | - | localStorage key for persisting selection |
defaultValue | string | - | Default selected value before localStorage hydration |
options | SplitButtonOption[] | - | Array of selectable options with value, label, optional icon |
Usage
import { SplitButton } from '@/ui/components';
import { faCopy, faFileCsv, faFileLines, faFileExport } from '@fortawesome/sharp-duotone-light-svg-icons';
// Basic export format selector
<SplitButton
groups={[
{
label: "Export Format",
storageKey: "exportFormat",
defaultValue: "csv",
options: [
{ value: "copy", label: "Copy to Clipboard", icon: faCopy },
{ value: "csv", label: "Export as CSV", icon: faFileCsv },
{ value: "json", label: "Export as JSON", icon: faFileLines },
]
}
]}
onAction={async (settings) => {
await handleExport(settings.exportFormat);
}}
getLabel={(settings) =>
settings.exportFormat === 'copy' ? 'Copy' : 'Export'
}
getIcon={(settings) =>
settings.exportFormat === 'copy' ? faCopy : faFileExport
}
successMessage={(settings) =>
`Exported as ${settings.exportFormat.toUpperCase()}`
}
/>
// Multiple option groups
<SplitButton
groups={[
{
label: "Format",
storageKey: "format",
defaultValue: "csv",
options: [
{ value: "csv", label: "CSV" },
{ value: "json", label: "JSON" },
]
},
{
label: "Size",
storageKey: "size",
defaultValue: "full",
options: [
{ value: "full", label: "Full Export" },
{ value: "summary", label: "Summary Only" },
]
}
]}
onAction={handleExport}
defaultLabel="Export"
defaultIcon={faFileExport}
/>