Smart Overflow

Use Smart Overflow when a compact product action group needs to preserve its most important actions as available width decreases. Lower-priority actions move into an accessible three-dot menu instead of wrapping or requiring horizontal scrolling.

Preview

Reduce motion:Off

Tune:Off

Inspect

Installation

Base UI Lucide Motion

npx shadcn@latest add @sona-ui/smart-overflow

Basic usage

document-actions.tsx

import SmartOverflow, { SmartOverflowAction } from "@/components/ui/smart-overflow/smart-overflow";
import { Archive, Eye, Pencil, Share2 } from "lucide-react";
 
export function DocumentActions() {
return (
  <SmartOverflow>
    <SmartOverflowAction id="edit" icon={<Pencil />} priority="primary">Edit</SmartOverflowAction>
    <SmartOverflowAction id="preview" icon={<Eye />} priority="primary">Preview</SmartOverflowAction>
    <SmartOverflowAction id="share" icon={<Share2 />} priority="secondary">Share</SmartOverflowAction>
    <SmartOverflowAction id="archive" icon={<Archive />} priority="overflow" destructive>Archive</SmartOverflowAction>
  </SmartOverflow>
);
}

Examples

Assign primary to actions that should remain visible longest. secondary actions move into the menu before primary actions, starting from the end of the child order. Use overflow for actions that should always live in the three-dot menu.

Use destructive for actions such as Archive or Delete. They retain their own visual treatment in the menu. Keep destructive actions in overflow unless they are genuinely the user's main next step.

Usage


"use client";
 
import { Archive, Copy, Eye, Pencil, Share2 } from "lucide-react";
import { useState } from "react";
 
import SmartOverflow, {
  SmartOverflowAction,
} from "@/components/ui/smart-overflow/smart-overflow";
 
export default function SmartOverflowDemo() {
  const [lastAction, setLastAction] = useState("No action selected");
 
  return (
    <div className="w-full min-w-[240px] rounded-xl border border-border bg-card p-3 text-card-foreground shadow-sm resize-x overflow-auto">
      <div className="mb-4">
        <p className="font-medium text-sm">Quarterly product update</p>
        <p className="mt-1 text-muted-foreground text-xs">
          Draft · Updated 2m ago
        </p>
      </div>
      <SmartOverflow>
        <SmartOverflowAction
          id="edit"
          icon={<Pencil />}
          priority="primary"
          onSelect={() => setLastAction("Edit selected")}
        >
          Edit
        </SmartOverflowAction>
        <SmartOverflowAction
          id="preview"
          icon={<Eye />}
          priority="primary"
          onSelect={() => setLastAction("Preview selected")}
        >
          Preview
        </SmartOverflowAction>
        <SmartOverflowAction
          id="share"
          icon={<Share2 />}
          priority="secondary"
          onSelect={() => setLastAction("Share selected")}
        >
          Share
        </SmartOverflowAction>
        <SmartOverflowAction
          id="duplicate"
          icon={<Copy />}
          priority="secondary"
          onSelect={() => setLastAction("Duplicate selected")}
        >
          Duplicate
        </SmartOverflowAction>
        <SmartOverflowAction
          id="archive"
          icon={<Archive />}
          priority="overflow"
          destructive
          onSelect={() => setLastAction("Archive selected")}
        >
          Archive
        </SmartOverflowAction>
      </SmartOverflow>
      <p aria-live="polite" className="mt-3 text-muted-foreground text-xs">
        {lastAction}
      </p>
    </div>
  );
}

API

Property	Type	Default	Description
`children`	`ReactNode`	`required`	Priority-aware action declarations. Only direct SmartOverflowAction children are rendered.
`ariaLabel`	`string`	`"Actions"`	Accessible label for the action group.
`moreLabel`	`string`	`"More actions"`	Accessible label for the three-dot trigger.
`disabled`	`boolean`	`false`	Whether every action is unavailable.
`className`	`string`	`undefined`	Additional CSS classes for the group container.
`actionClassName`	`string`	`undefined`	Additional CSS classes applied to each visible action.
`moreButtonClassName`	`string`	`undefined`	Additional CSS classes applied to the three-dot trigger.
`menuClassName`	`string`	`undefined`	Additional CSS classes for the overflow menu.

Accessibility

The visible controls use button semantics. Hidden actions remain available through an accessible three-dot menu with Base UI menu keyboard navigation and focus management. If a focused action moves into overflow after a resize, focus returns to the three-dot trigger. Layout motion is disabled for people who prefer reduced motion.

Styling

The component uses the consumer's semantic tokens for surfaces, text, focus, and destructive menu actions. Use the class name props to adapt the action buttons, trigger, or menu surface without changing its responsive priority behavior.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Was this page helpful?

Your response helps us improve component docs.