@softwarity/split-button

An Angular directive that creates a Material Design 3 split button with a dropdown menu for secondary actions.

Live Demo | Release Notes

Features

• Material Design 3 Compliant - Follows M3 button specifications
• 5 Button Variants - Text, Filled, Tonal, Outlined, Elevated
• Responsive to Theme - Automatically adapts to light/dark color schemes
• MatMenu Integration - Works seamlessly with Angular Material's menu component
• Material 3 Ready - Uses M3 design tokens for theming (--mat-sys-*)
• Standalone Directive - Easy to import in any Angular 21+ application
• Accessible - Keyboard navigation and ARIA support

Installation

npm install @softwarity/split-button

Peer Dependencies

Package	Version
@angular/core	>= 21.0.0
@angular/material	>= 21.0.0

Usage

1. Import the directive in your component

import { SplitButtonDirective } from '@softwarity/split-button';
import { MatMenuModule } from '@angular/material/menu';

@Component({
  selector: 'app-my-component',
  imports: [SplitButtonDirective, MatMenuModule],
  template: `...`
})
export class MyComponent {}

2. Add the appSplitButton directive to your button

<!-- Text button (default) -->
<button appSplitButton [appSplitButtonTrigger]="trigger" (click)="onSave()">
  Save
</button>
<span [matMenuTriggerFor]="menu" #trigger="matMenuTrigger"></span>
<mat-menu #menu="matMenu">
  <button mat-menu-item (click)="onSaveAs()">Save As...</button>
  <button mat-menu-item (click)="onSaveDraft()">Save Draft</button>
</mat-menu>

<!-- Filled variant -->
<button appSplitButton="filled" [appSplitButtonTrigger]="trigger" (click)="onSubmit()">
  Submit
</button>

<!-- Outlined variant -->
<button appSplitButton="outlined" [appSplitButtonTrigger]="trigger" (click)="onAction()">
  Action
</button>

<!-- Tonal variant -->
<button appSplitButton="tonal" [appSplitButtonTrigger]="trigger" (click)="onProcess()">
  Process
</button>

<!-- Elevated variant -->
<button appSplitButton="elevated" [appSplitButtonTrigger]="trigger" (click)="onExport()">
  Export
</button>

API

Inputs

Input	Type	Default	Description
appSplitButton	'' | 'filled' | 'tonal' | 'outlined' | 'elevated'	''	Button variant following Material Design 3 guidelines
appSplitButtonTrigger	MatMenuTrigger	undefined	Reference to the MatMenuTrigger for the dropdown menu
disabled	boolean	false	Whether the button is disabled

Button Variants

Variant	Description
Text (default)	Lowest emphasis, for less important actions
Filled	High emphasis, for primary actions
Tonal	Medium emphasis with a container color from the secondary palette
Outlined	Medium emphasis with a border outline
Elevated	Medium emphasis with a shadow elevation

Theming (Optional)

The directive automatically injects its styles. If you want to customize the colors, you can use the optional SCSS mixin:

@use '@softwarity/split-button/split-button-theme' as split-button;

// Customize split-button colors
@include split-button.overrides((
  filled-container-color: #ff5722,
  filled-label-color: #ffffff
));

Available Tokens

The overrides mixin accepts a map of tokens to customize the appearance:

Token	Default	Description
text-label-color	var(--mat-sys-primary)	Label color for text variant
filled-container-color	var(--mat-sys-primary)	Container color for filled variant
filled-label-color	var(--mat-sys-on-primary)	Label color for filled variant
outlined-outline-color	var(--mat-sys-outline)	Border color for outlined variant
outlined-label-color	var(--mat-sys-primary)	Label color for outlined variant
tonal-container-color	var(--mat-sys-secondary-container)	Container color for tonal variant
tonal-label-color	var(--mat-sys-on-secondary-container)	Label color for tonal variant
elevated-container-color	var(--mat-sys-surface-container-low)	Container color for elevated variant
elevated-label-color	var(--mat-sys-primary)	Label color for elevated variant

Examples

// Customize filled button colors
@include split-button.overrides((
  filled-container-color: light-dark(#6750a4, #d0bcff),
  filled-label-color: light-dark(#ffffff, #381e72)
));

// Use Material 3 system colors for tonal variant
@include split-button.overrides((
  tonal-container-color: var(--mat-sys-tertiary-container),
  tonal-label-color: var(--mat-sys-on-tertiary-container)
));

// Custom brand colors
@include split-button.overrides((
  filled-container-color: #ff5722,
  filled-label-color: #ffffff
));

Examples

Save Action with Alternatives

<button appSplitButton="filled" [appSplitButtonTrigger]="saveTrigger" (click)="onSave()">
  Save
</button>
<span [matMenuTriggerFor]="saveMenu" #saveTrigger="matMenuTrigger"></span>
<mat-menu #saveMenu="matMenu">
  <button mat-menu-item (click)="onSaveAs()">Save As...</button>
  <button mat-menu-item (click)="onSaveDraft()">Save Draft</button>
  <button mat-menu-item (click)="onSaveAndClose()">Save & Close</button>
</mat-menu>

Export with Format Options

<button appSplitButton="outlined" [appSplitButtonTrigger]="exportTrigger" (click)="onExportPDF()">
  Export PDF
</button>
<span [matMenuTriggerFor]="exportMenu" #exportTrigger="matMenuTrigger"></span>
<mat-menu #exportMenu="matMenu">
  <button mat-menu-item (click)="onExportCSV()">Export CSV</button>
  <button mat-menu-item (click)="onExportXLSX()">Export Excel</button>
  <button mat-menu-item (click)="onExportJSON()">Export JSON</button>
</mat-menu>

Disabled State

<button appSplitButton="filled" [appSplitButtonTrigger]="trigger" [disabled]="true">
  Disabled
</button>

License

MIT