SplitButton

A split button combines a primary action with a dropdown menu of secondary actions. The main button area triggers the default action, while a dropdown arrow reveals additional options.

Split buttons are ideal when you have a common default action but need to expose related alternatives without cluttering your UI with multiple buttons.

Basic Usage

Create split buttons using SplitButton(), then chain PrimaryAction() and SecondaryAction() methods:

csharp

dotnet run

Interaction

• Click the label or press Enter to trigger the primary action
• Click the arrow (▼) or press Down to open the dropdown menu
• Escape closes the dropdown without selecting

How It Works

The split button renders as [ Label ▼ ] with two distinct click regions:

Region	Mouse Action	Keyboard Action
Label area	Triggers primary action	Enter or Space
Arrow (▼)	Opens dropdown menu	Down arrow

When the dropdown is open:

• Up/Down arrows navigate between options
• Enter selects the highlighted option
• Escape closes without selecting

Event Handlers

Primary Action

Use PrimaryAction() to set the label and handler for the main button:

ctx.SplitButton()
   .PrimaryAction("Run", e => RunDefaultCommand())

The handler receives SplitButtonClickedEventArgs with:

• Widget - The source SplitButtonWidget
• Node - The underlying SplitButtonNode
• Context - Access to notifications, focus, popups, and app services

Secondary Actions

Add dropdown menu items with SecondaryAction():

ctx.SplitButton()
   .PrimaryAction("Run", _ => RunDefault())
   .SecondaryAction("Run with Debugger", _ => RunDebug())
   .SecondaryAction("Run Tests", _ => RunTests())
   .SecondaryAction("Run Benchmarks", _ => RunBenchmarks())

Actions appear in the dropdown in the order they're added.

Async Handlers

Both primary and secondary actions support async handlers:

ctx.SplitButton()
   .PrimaryAction("Deploy", async e => {
       await DeployToProductionAsync();
       e.Context.Notifications.Post(
           new Notification("Deployed", "Successfully deployed to production"));
   })
   .SecondaryAction("Deploy to Staging", async e => {
       await DeployToStagingAsync();
   })

Dropdown Opened Callback

Use OnDropdownOpened() to react when the dropdown menu opens:

ctx.SplitButton()
   .PrimaryAction("Options", _ => { })
   .OnDropdownOpened(() => Analytics.Track("dropdown_opened"))
   .SecondaryAction("Option A", _ => { })
   .SecondaryAction("Option B", _ => { })

This is useful for:

• Analytics tracking
• Canceling timeouts (e.g., on notification cards)
• Lazy-loading menu content

Multiple Split Buttons

You can use multiple split buttons together for complex toolbars:

csharp

dotnet run

Use Cases

Split buttons work well for:

Scenario	Example
File operations	Save / Save As / Save All
Deployment	Deploy / Deploy to Staging / Rollback
Creation actions	New File / From Template / Duplicate
Run commands	Run / Debug / Profile
Export options	Export / Export as PDF / Export as CSV

Keyboard Navigation

Key	Action
Tab	Focus the split button
Enter / Space	Trigger primary action
Down	Open dropdown menu
Up / Down (in menu)	Navigate options
Enter (in menu)	Select option
Escape	Close dropdown

Related Widgets

• Button - Simple single-action buttons
• Picker - Dropdown selection without primary action
• List - Scrollable item selection