Split Button

Two-part button with main action and settings dropdown

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/duotone-regular-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}
/>

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

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

import { SplitButton } from '@/ui/components'; import { faCopy, faFileCsv, faFileLines, faFileExport } from '@fortawesome/duotone-regular-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} />