# Animated Trigger Menu for UI SDK (/docs/components/trigger-menu)

Typing @ or / opens a menu at the cursor, with rows cascading in and a gliding highlight.

```tsx title="example.tsx"
import * as React from "react"

import {
  createTriggerMenuController,
  TriggerMenu,
  TriggerMenuContent,
  type TriggerMenuDataItem,
  TriggerMenuEmpty,
  TriggerMenuGroup,
  TriggerMenuGroupLabel,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuItemIcon,
  TriggerMenuList,
  TriggerMenuStatus,
} from "@/components/keyframery/trigger-menu"

const people = [
  { value: "ines", label: "Dana Whitfield", hint: "Owner" },
  { value: "kofi", label: "Marcus Bell", hint: "Booked the van" },
  { value: "aiko", label: "Joanna Park", hint: "Has the keys" },
  { value: "tomas", label: "Tomás Reyes", hint: "Joins Friday" },
]

const actions = [
  { value: "date", label: "date", hint: "Insert a date", icon: "M3 4.5h10v8.5H3zM3 7h10M6 3v3M10 3v3" },
  { value: "place", label: "place", hint: "Pin a place", icon: "M8 14s4.5-4 4.5-7.5a4.5 4.5 0 0 0-9 0C3.5 10 8 14 8 14zM8 8a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3z" },
  { value: "split", label: "split", hint: "Split a cost", icon: "M8 2.5v11M11 5H6.75a1.75 1.75 0 0 0 0 3.5h2.5a1.75 1.75 0 0 1 0 3.5H5" },
  { value: "poll", label: "poll", hint: "Ask the group", icon: "M4 13V9M8 13V3.5M12 13V6.5" },
]

const initials = (name: string) =>
  name
    .split(" ")
    .map((part) => part[0])
    .join("")

export default function TriggerMenuDemo() {
  const [menu] = React.useState(createTriggerMenuController)
  return (
    <div className="w-[400px]">
      <div className="mb-2 flex items-baseline justify-between">
        <label htmlFor="trip-reply" className="text-[13px] leading-none font-medium">
          Reply to moving day
        </label>
        <span className="flex items-center gap-1 text-[12px] text-muted-foreground">
          {[
            { id: "kf-mention", char: "@", label: "people" },
            { id: "kf-action", char: "/", label: "actions" },
          ].map((t) => (
            <button
              key={t.id}
              id={t.id}
              type="button"
              onMouseDown={(event) => event.preventDefault()}
              onClick={() => menu.open({ trigger: t.char })}
              className="flex h-6 cursor-pointer items-center gap-1.5 rounded-[7px] px-1.5 outline-none transition-[scale,color] duration-200 ease-pop hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring active:scale-[0.96] motion-reduce:transition-none"
            >
              <kbd className="grid h-[18px] min-w-[18px] place-items-center rounded-[5px] bg-muted px-1 font-sans text-[11px] font-medium text-foreground">
                {t.char}
              </kbd>
              {t.label}
            </button>
          ))}
        </span>
      </div>
      <TriggerMenu
        controller={menu}
        triggers={[
          { char: "@", items: people, spaces: 1 },
          { char: "/", items: actions, insert: (item) => `/${item.label} ` },
        ]}
      >
        <TriggerMenuInput
          id="trip-reply"
          spellCheck={false}
          placeholder="Van comes at eight. Who is bringing tape?"
        />
        <TriggerMenuStatus />
        <TriggerMenuContent className="w-60">
          <TriggerMenuEmpty>No match</TriggerMenuEmpty>
          <TriggerMenuList>
            {(state) =>
              state.trigger === "/" ? (
                <TriggerMenuGroup>
                  <TriggerMenuGroupLabel>Actions</TriggerMenuGroupLabel>
                  {(state.items as TriggerMenuDataItem[]).map((item) => {
                    const action = actions.find((a) => a.value === item.value)
                    return (
                      <TriggerMenuItem key={item.value} value={item.value} label={item.label}>
                        <TriggerMenuItemIcon>
                          <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
                            <path d={action?.icon} />
                          </svg>
                        </TriggerMenuItemIcon>
                        <span className="font-medium">/{item.label}</span>
                        <span className="ms-auto text-[12px] text-muted-foreground">{action?.hint}</span>
                      </TriggerMenuItem>
                    )
                  })}
                </TriggerMenuGroup>
              ) : (
                <TriggerMenuGroup>
                  <TriggerMenuGroupLabel>People on this trip</TriggerMenuGroupLabel>
                  {(state.items as TriggerMenuDataItem[]).map((item) => {
                    const person = people.find((p) => p.value === item.value)
                    return (
                      <TriggerMenuItem key={item.value} value={item.value} label={item.label}>
                        <span className="grid size-5 shrink-0 place-items-center rounded-full bg-muted text-[9px] font-semibold text-muted-foreground shadow-[inset_0_0_0_1px_rgb(0_0_0/0.04)] group-data-highlighted/item:bg-background dark:group-data-highlighted/item:bg-popover">
                          {initials(item.label)}
                        </span>
                        <span className="truncate">{item.label}</span>
                        <span className="ms-auto shrink-0 text-[12px] text-muted-foreground">{person?.hint}</span>
                      </TriggerMenuItem>
                    )
                  })}
                </TriggerMenuGroup>
              )
            }
          </TriggerMenuList>
        </TriggerMenuContent>
      </TriggerMenu>
    </div>
  )
}
```

## Installation [#installation]

```bash
npx shadcn@latest add @keyframery/trigger-menu
```

This adds `components/keyframery/trigger-menu.tsx` and its primitive, `components/keyframery/primitives/trigger-menu.tsx`, to your project, and installs `@ui-sdk/react`. The motion tokens are added to your global CSS the first time you install a component.

## Usage [#usage]

```tsx
import {
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuEmpty,
  TriggerMenuGroup,
  TriggerMenuGroupLabel,
  TriggerMenuHint,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuItemIcon,
  TriggerMenuItems,
  TriggerMenuList,
  TriggerMenuSeparator,
  TriggerMenuStatus,
} from "@/components/keyframery/trigger-menu"
```

The parts and props are the same as UI SDK's Trigger Menu. For every prop, see the [UI SDK trigger menu reference](https://ui-sdk.dev/docs/components/trigger-menu).

## What moves [#what-moves]

| Move        | What you see                              |
| ----------- | ----------------------------------------- |
| **Unfold**  | Typing @ or / opens a menu at the cursor. |
| **Cascade** | Rows arrive one after another.            |
| **Glide**   | One highlight glides between items.       |

Timing and springiness follow the [motion style](/docs/motion-styles) you set, so this component moves like the rest of your app.

## Swap the import [#swap-the-import]

Already using UI SDK's trigger menu with your own styles? Keep your markup and change one line. The primitive adds motion and nothing else.

```tsx
// Before
import { … } from "@ui-sdk/react/trigger-menu"

// After: same parts, same props, now animated
import { … } from "@/components/keyframery/primitives/trigger-menu"
```

## Parts [#parts]

The finished component exports 13 parts:

`TriggerMenu`, `TriggerMenuContent`, `TriggerMenuEmpty`, `TriggerMenuGroup`, `TriggerMenuGroupLabel`, `TriggerMenuHint`, `TriggerMenuInput`, `TriggerMenuItem`, `TriggerMenuItemIcon`, `TriggerMenuItems`, `TriggerMenuList`, `TriggerMenuSeparator`, `TriggerMenuStatus`

## Accessibility [#accessibility]

Keyboard, focus and screen-reader behaviour come from UI SDK and are not changed. With reduced motion turned on, nothing in the trigger menu moves: changes happen at once or with a short fade. More in [Accessibility](/docs/accessibility).

## Source [#source]

The code that lands in your project. It is yours to change.

**components/keyframery/trigger-menu.tsx**

```tsx
"use client"

/* Styled trigger menu: the animated primitive plus the Keyframery look. */

import {
  createTriggerMenuController,
  textFieldAdapter,
  TriggerMenu as TriggerMenuRoot,
  TriggerMenuContent as TriggerMenuContentPart,
  type TriggerMenuData,
  TriggerMenuEmpty as TriggerMenuEmptyPart,
  TriggerMenuGroup as TriggerMenuGroupPart,
  TriggerMenuGroupLabel as TriggerMenuGroupLabelPart,
  TriggerMenuHint as TriggerMenuHintPart,
  TriggerMenuInput as TriggerMenuInputPart,
  TriggerMenuItem as TriggerMenuItemPart,
  TriggerMenuItemIcon as TriggerMenuItemIconPart,
  TriggerMenuList as TriggerMenuListPart,
  type TriggerMenuProps,
  TriggerMenuSeparator as TriggerMenuSeparatorPart,
  TriggerMenuStatus as TriggerMenuStatusPart,
} from "@/components/keyframery/primitives/trigger-menu"
import * as React from "react"

import { cn } from "@/lib/utils"

/* The sheet. Its motion comes from the primitive. */
const sheet = cn(
  "group/content m-0 flex w-64 flex-col border-0 p-0 outline-none",
  "[--list-height:var(--available-height)]",
  "rounded-[14px] bg-popover text-popover-foreground",
  "shadow-[0_0_0_1px_rgb(0_0_0/0.06),0_2px_6px_-2px_rgb(0_0_0/0.08),0_12px_32px_-8px_rgb(0_0_0/0.18)]",
  "dark:shadow-[0_0_0_1px_rgb(255_255_255/0.08),0_12px_32px_-8px_rgb(0_0_0/0.7)]",
)

/* One row per suggestion. Focus stays in the field; the list's gliding highlight is the cursor. */
const row = cn(
  "group/item relative flex min-h-8 cursor-default items-center gap-2 rounded-[8px] px-2 py-1.5 text-[13px] leading-4 outline-none select-none",
  "data-highlighted:text-accent-foreground",
  "data-disabled:text-muted-foreground/60 data-disabled:data-highlighted:text-muted-foreground/60",
  /* Rows without an icon keep the icon column when another row in the list has one. */
  "[[data-has-icons]_&:not([data-has-icon])]:ps-8",
)

function TriggerMenu<T = string>(props: TriggerMenuProps<T>) {
  return <TriggerMenuRoot<T> {...props} />
}

/* The field people type in: a textarea by default, an input through `render`. */
function TriggerMenuInput({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuInputPart>) {
  return (
    <TriggerMenuInputPart
      className={cn(
        "block min-h-9 w-full min-w-0 resize-none rounded-[10px] bg-background px-3 py-2 text-[13px] leading-5 text-foreground outline-none placeholder:text-muted-foreground",
        "[field-sizing:content] [&:is(textarea)]:min-h-[84px]",
        "shadow-[0_0_0_1px_rgb(0_0_0/0.09),0_1px_2px_rgb(0_0_0/0.05)] dark:shadow-[0_0_0_1px_rgb(255_255_255/0.1)]",
        "transition-shadow duration-[calc(150ms*var(--kf-speed,1))] motion-reduce:transition-none!",
        "hover:shadow-[0_0_0_1px_rgb(0_0_0/0.16),0_1px_2px_rgb(0_0_0/0.05)] dark:hover:shadow-[0_0_0_1px_rgb(255_255_255/0.16)]",
        "focus-visible:shadow-[0_0_0_1px_var(--ring)] focus-visible:ring-[3px] focus-visible:ring-ring/25 dark:focus-visible:shadow-[0_0_0_1px_var(--ring)]",
        "aria-invalid:shadow-[0_0_0_1px_var(--destructive)] aria-invalid:focus-visible:ring-destructive/25 dark:aria-invalid:shadow-[0_0_0_1px_var(--destructive)]",
        "disabled:cursor-not-allowed disabled:opacity-50 read-only:bg-muted/40",
        className,
      )}
      {...props}
    />
  )
}

function TriggerMenuContent({
  className,
  children,
  sideOffset = 6,
  ...props
}: React.ComponentProps<typeof TriggerMenuContentPart>) {
  return (
    <TriggerMenuContentPart
      sideOffset={sideOffset}
      className={cn(sheet, className)}
      {...props}
    >
      {children ?? <TriggerMenuList />}
    </TriggerMenuContentPart>
  )
}

function TriggerMenuList({
  className,
  children,
  ...props
}: React.ComponentProps<typeof TriggerMenuListPart>) {
  return (
    <TriggerMenuListPart
      className={cn(
        "max-h-[min(calc(var(--list-height,100vh)-8px),18rem)] scroll-py-1.5 overflow-y-auto overscroll-contain p-1.5 outline-none",
        "aria-busy:opacity-60 before:rounded-[8px] before:bg-accent",
        "has-[[data-disabled][data-highlighted]]:before:bg-accent/50",
        "group-has-[[data-slot=trigger-menu-empty][data-empty]]/content:hidden",
        className,
      )}
      {...props}
    >
      {children ?? ((state) => <TriggerMenuItems items={state.items} />)}
    </TriggerMenuListPart>
  )
}

function TriggerMenuItem<T = string>({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuItemPart<T>>) {
  return <TriggerMenuItemPart<T> className={cn(row, className)} {...props} />
}

function TriggerMenuItemIcon({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuItemIconPart>) {
  return (
    <TriggerMenuItemIconPart
      className={cn(
        "flex size-4 shrink-0 items-center justify-center text-muted-foreground [&>svg]:size-4",
        "group-data-highlighted/item:text-current",
        "rtl:data-mirror:-scale-x-100",
        className,
      )}
      {...props}
    />
  )
}

function TriggerMenuGroup({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuGroupPart>) {
  return <TriggerMenuGroupPart className={cn("flex flex-col", className)} {...props} />
}

function TriggerMenuGroupLabel({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuGroupLabelPart>) {
  return (
    <TriggerMenuGroupLabelPart
      className={cn(
        "px-2 pt-1.5 pb-1 text-[11px] leading-4 font-medium text-muted-foreground select-none",
        className,
      )}
      {...props}
    />
  )
}

function TriggerMenuSeparator({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuSeparatorPart>) {
  return (
    <TriggerMenuSeparatorPart
      className={cn("-mx-1.5 my-1.5 h-px bg-border", className)}
      {...props}
    />
  )
}

/* Shown while nothing matches. Rendering it keeps the menu open with no matches. */
function TriggerMenuEmpty({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuEmptyPart>) {
  return (
    <TriggerMenuEmptyPart
      className={cn(
        "hidden px-3 py-5 text-center text-[13px] text-muted-foreground data-empty:block data-loading:block",
        className,
      )}
      {...props}
    />
  )
}

/* A polite live region. Hidden from sight by default, heard by screen readers. */
function TriggerMenuStatus({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuStatusPart>) {
  return <TriggerMenuStatusPart className={cn("sr-only", className)} {...props} />
}

/* Ghost text at the caret for the arguments still to type. */
function TriggerMenuHint({
  className,
  ...props
}: React.ComponentProps<typeof TriggerMenuHintPart>) {
  return (
    <TriggerMenuHintPart
      className={cn("pointer-events-none text-[13px] text-muted-foreground/70 select-none", className)}
      {...props}
    />
  )
}

/* Renders suggestions passed as data with the styled parts above. */
function TriggerMenuItems({ items }: { items?: TriggerMenuData<unknown> }) {
  return (items ?? []).map((entry, index) => {
    if (typeof entry === "string") {
      return (
        <TriggerMenuItem key={entry} value={entry} label={entry}>
          {entry}
        </TriggerMenuItem>
      )
    }
    if ("type" in entry && entry.type === "separator") {
      return <TriggerMenuSeparator key={`separator-${index}`} />
    }
    if ("type" in entry && entry.type === "group") {
      return (
        <TriggerMenuGroup key={`group-${entry.label ?? index}`}>
          {entry.label && <TriggerMenuGroupLabel>{entry.label}</TriggerMenuGroupLabel>}
          <TriggerMenuItems items={entry.items} />
        </TriggerMenuGroup>
      )
    }
    const { value, label, disabled, keywords } = entry
    return (
      <TriggerMenuItem<unknown>
        key={typeof value === "string" ? value : index}
        value={value}
        label={label}
        disabled={disabled}
        keywords={keywords}
      >
        {label}
      </TriggerMenuItem>
    )
  })
}

export type { TriggerMenuData, TriggerMenuDataItem } from "@/components/keyframery/primitives/trigger-menu"
export {
  createTriggerMenuController,
  textFieldAdapter,
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuEmpty,
  TriggerMenuGroup,
  TriggerMenuGroupLabel,
  TriggerMenuHint,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuItemIcon,
  TriggerMenuItems,
  TriggerMenuList,
  TriggerMenuSeparator,
  TriggerMenuStatus,
}
```

**components/keyframery/primitives/trigger-menu.tsx**

```tsx
"use client"

/* Animated drop-in for `@ui-sdk/react/trigger-menu`: same parts, same props. Swap the import and keep your code.
   This file adds motion only. Colours, radii, shadows and spacing stay yours.

   - Content: Unfold from the caret (scale 0.86, 6px blur, 8px toward the line; spring in, quick out).
   - List: rows Cascade in as the list opens, and one highlight Glides between them as you
     arrow through (CSS anchor positioning). Its neutral surface follows the text colour; give
     `before:bg-…` and `before:rounded-…` to restyle it. */

import {
  TriggerMenuContent as TriggerMenuContentPart,
  TriggerMenuItem as TriggerMenuItemPart,
  TriggerMenuList as TriggerMenuListPart,
} from "@ui-sdk/react/trigger-menu"
import * as React from "react"

import { cn } from "@/lib/utils"

export * from "@ui-sdk/react/trigger-menu"

function TriggerMenuContent({ className, ...props }: React.ComponentProps<typeof TriggerMenuContentPart>) {
  return (
    <TriggerMenuContentPart
      className={cn(
        "group/kf-tm origin-(--transform-origin)",
        "[transition:opacity_calc(380ms*var(--kf-speed,1))_var(--ease-spring),scale_calc(380ms*var(--kf-speed,1))_var(--ease-spring),translate_calc(380ms*var(--kf-speed,1))_var(--ease-spring),filter_calc(380ms*var(--kf-speed,1))_var(--ease-spring)]",
        "data-[side=bottom]:[--kf-from:0_-8px] data-[side=top]:[--kf-from:0_8px] data-[side=left]:[--kf-from:8px_0] data-[side=right]:[--kf-from:-8px_0]",
        "data-starting-style:[translate:var(--kf-from,0_0)] data-starting-style:scale-[0.86] data-starting-style:opacity-0 data-starting-style:blur-[6px]",
        "data-ending-style:scale-[0.96] data-ending-style:opacity-0 data-ending-style:blur-[2px]",
        "data-ending-style:[transition:opacity_calc(150ms*var(--kf-speed,1))_var(--ease-house),scale_calc(150ms*var(--kf-speed,1))_var(--ease-house),translate_calc(150ms*var(--kf-speed,1))_var(--ease-house),filter_calc(150ms*var(--kf-speed,1))_var(--ease-house)]",
        "motion-reduce:[transition:none]!",
        className,
      )}
      {...props}
    />
  )
}

function TriggerMenuList({ className, ...props }: React.ComponentProps<typeof TriggerMenuListPart>) {
  return (
    <TriggerMenuListPart
      className={cn(
        /* Cascade: the list's children, one after another, while the content unfolds. */
        "[&>*]:transition-[opacity,translate,filter] [&>*]:duration-[calc(420ms*var(--kf-speed,1))] [&>*]:ease-spring",
        "[&>*]:[transition-delay:calc((min(sibling-index(),10)-1)*calc(32ms*var(--kf-speed,1)))]",
        "group-data-starting-style/kf-tm:[&>*]:translate-y-2 group-data-starting-style/kf-tm:[&>*]:opacity-0 group-data-starting-style/kf-tm:[&>*]:blur-[4px]",
        "group-data-ending-style/kf-tm:[&>*]:[transition-delay:0ms]",
        "group-data-starting-style/kf-tm:[&>*]:[transition:none]",
        /* Glide */
        "relative isolate [anchor-scope:--kf-hl]",
        "before:pointer-events-none before:absolute before:-z-10 before:hidden before:bg-[color-mix(in_oklch,currentColor_9%,transparent)]",
        "before:[position-anchor:--kf-hl] before:top-[anchor(top)] before:right-[anchor(right)] before:bottom-[anchor(bottom)] before:left-[anchor(left)]",
        "before:[transition:top_calc(260ms*var(--kf-speed,1))_var(--ease-spring),right_calc(260ms*var(--kf-speed,1))_var(--ease-spring),bottom_calc(260ms*var(--kf-speed,1))_var(--ease-spring),left_calc(260ms*var(--kf-speed,1))_var(--ease-spring),opacity_calc(150ms*var(--kf-speed,1))_var(--ease-house)]",
        "has-[[data-highlighted]]:before:block starting:before:opacity-0",
        "motion-reduce:[&>*]:[transition:none] motion-reduce:before:[transition:none]!",
        className,
      )}
      {...props}
    />
  )
}

function TriggerMenuItem<T = string>({ className, ...props }: React.ComponentProps<typeof TriggerMenuItemPart<T>>) {
  return <TriggerMenuItemPart<T> className={cn("data-highlighted:[anchor-name:--kf-hl]", className)} {...props} />
}

export { TriggerMenuContent, TriggerMenuItem, TriggerMenuList }
```

## Questions

### How does the animated Trigger Menu for UI SDK move?

Unfold: Typing @ or / opens a menu at the cursor. Cascade: Rows arrive one after another. Glide: One highlight glides between items.

### Do I need Motion or Framer Motion for the animated Trigger Menu?

No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.

### Can I keep my own styling and only take the motion?

Yes. Import from `@/components/keyframery/primitives/trigger-menu` instead. It has the same parts and props as `@ui-sdk/react/trigger-menu` and adds motion only.

### What happens to the Trigger Menu when someone turns on reduced motion?

Nothing moves. State changes happen at once, or with a short fade.
