Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Actions

SplitButton

Combines a primary native action with a separate keyboard-accessible menu.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add split-button

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import SplitButton from './components/ui/split-button/SplitButton.vue'

const options = [
  { id: 'draft', label: 'Save as draft' },
  { id: 'template', label: 'Save as template' },
]
function saveAs(item: { id: string }) {
  console.log(item.id)
}
</script>

<template>
  <SplitButton :items="options" menu-label="More save options" @select="saveAs">Save</SplitButton>
</template>

The primary button preserves native form behavior. Menu arrows wrap, Home and End move to the edges, typeahead searches labels, and Escape closes and restores trigger focus.

When to use it

Primary save plus alternatives

Keep Save as the main action and put format choices in the adjacent menu.

Send with options

Offer a direct send action and alternate scheduling actions.

More examples

Save alternatives

The primary action and menu selection are separate events.

Save alternatives
<script setup lang="ts">
import SplitButton from './components/ui/split-button/SplitButton.vue'

const options = [
  { id: 'draft', label: 'Save as draft' },
  { id: 'copy', label: 'Save a copy' },
]
function save() {
  /* Save the current document. */
}
function saveAs(id: string) {
  console.log('Selected save action:', id)
}
</script>
<template>
  <SplitButton
    :items="options"
    menu-label="Other save options"
    @action="save"
    @select="saveAs($event.id)"
  >
    Save
  </SplitButton>
</template>

Send options

Disable an unavailable alternative without disabling the primary action.

Send options
<script setup lang="ts">
import SplitButton from './components/ui/split-button/SplitButton.vue'

const options = [
  { id: 'schedule', label: 'Schedule send' },
  { id: 'test', label: 'Send test', disabled: true },
]
</script>
<template>
  <SplitButton
    :items="options"
    menu-label="Other send options"
    variant="secondary"
    @action="$emit('send')"
    @select="$emit('option', $event.id)"
  >
    Send now
  </SplitButton>
</template>

Keep the usual export one click away

Make the most used format the primary action and group the alternatives in the adjacent menu.

Keep the usual export one click away
<script setup lang="ts">
import { ref } from 'vue'
import SplitButton from './components/ui/split-button/SplitButton.vue'

const alternatives = [
  { id: 'JSON', label: 'Export JSON' },
  { id: 'TSV', label: 'Export TSV' },
]
const lastExport = ref('')
</script>

<template>
  <div class="space-y-2">
    <SplitButton
      :items="alternatives"
      menu-label="Other export formats"
      @action="lastExport = 'CSV'"
      @select="lastExport = $event.id"
    >
      Export CSV
    </SplitButton>
    <p role="status" class="min-h-5 text-sm text-muted-foreground">
      {{ lastExport ? `${lastExport} export selected` : '' }}
    </p>
  </div>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

SplitButton

Complete API for SplitButton
NameType or signatureDefaultWhat it does
itemspropreadonly SplitButtonItem[]RequiredData items displayed by this component.
menuLabelpropstringRequiredmenuLabel supplies the trigger and menu accessible name.
variantprop"default" | "destructive" | "secondary" | "outline" | undefined"default"Choose the visual treatment for this component.
sizeprop"sm" | "md" | "lg" | undefined"md"Choose the visual size. Medium is the usual default where available.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
loadingpropboolean | undefinedNot setShow that an action is in progress and prevent repeat activation.
typeprop"button" | "submit" | "reset" | undefined"button"Choose the native HTML control type or action behavior.
widthpropnumber | undefined224Choose the width of this content.
gappropnumber | undefined12Space in pixels between the trigger and floating content.
alignprop"start" | "end" | "center" | undefined"end"Choose how content aligns within its container.
sideprop"top" | "bottom" | undefined"bottom"Choose the side on which this content appears.
openmodelboolean | undefinedfalseCurrent open state. Use v-model:open to keep it in sync with your page.
selectevent[item: SplitButtonItem]—Emitted when the user selects an item.
actionevent[event: MouseEvent]—Emitted when action happens.
update:openevent[value: boolean]—Requests a new open value from the parent.
defaultslot() => unknownRequiredContent shown inside SplitButton.
triggerslot(() => unknown) | undefinedOptionalContent for the trigger area of SplitButton.
itemslot((props: { item: SplitButtonItem; }) => unknown) | undefinedOptionalContent for the item area of SplitButton.
actionElementexposedHTMLButtonElement | null—Access action element from a component template ref.
triggerElementexposedHTMLButtonElement | null—Access trigger element from a component template ref.
focusexposed() => void | undefined—Move keyboard focus to this control.
openexposed(fromLast?: boolean) => void—Open this component from application code.
closeexposed(restoreFocus?: boolean) => void—Close this component from application code.
Public type definitions
Public types
// packages/frameworks/vue/components/split-button/types.ts
// ------- IMPORTS -------

import type { splitButtonActionSizes, splitButtonVariants } from './styles'

// ------- TYPES -------

export interface SplitButtonItem {
  id: string
  label: string
  disabled?: boolean
  destructive?: boolean
}

export interface SplitButtonProps {
  items: readonly SplitButtonItem[]
  menuLabel: string
  variant?: keyof typeof splitButtonVariants
  size?: keyof typeof splitButtonActionSizes
  disabled?: boolean
  loading?: boolean
  type?: 'button' | 'submit' | 'reset'
  width?: number
  gap?: number
  align?: 'start' | 'center' | 'end'
  side?: 'top' | 'bottom'
}


// packages/frameworks/vue/components/split-button/styles.ts
// Edit both halves together here; public visual prop types follow these map keys.
export const splitButtonVariants = {
  default: 'border-primary bg-primary text-primary-foreground hover:bg-primary-hover',
  secondary: 'border-secondary bg-secondary text-secondary-foreground hover:bg-secondary-hover',
  outline: 'border-control-border bg-clip-padding bg-control text-foreground hover:bg-secondary',
  destructive:
    'border-destructive bg-destructive text-destructive-foreground hover:bg-destructive-hover',
} as const

export const splitButtonOpenVariants: Record<keyof typeof splitButtonVariants, string> = {
  default: 'bg-primary-hover',
  secondary: 'bg-secondary-hover',
  outline: 'bg-secondary',
  destructive: 'bg-destructive-hover',
}

export const splitButtonActionSizes = {
  sm: 'h-8 px-3 text-xs',
  md: 'h-10 px-4 text-sm',
  lg: 'h-12 px-6 text-base',
} as const

export const splitButtonTriggerSizes: Record<keyof typeof splitButtonActionSizes, string> = {
  sm: 'size-8',
  md: 'size-10',
  lg: 'size-12',
}

Implementation notes

  • The menuLabel names the separate menu trigger; the default slot names the primary button.
  • The primary button supports type="submit"; a menu choice never submits the form.
  • The primary action and separate menu trigger both give slight press feedback.

Accessibility and localization

  • Use short, distinct labels for the primary and alternative actions.
  • Escape closes the menu and restores focus to its trigger.

Source contract and editing guidance