ButtonList

Horizontal row of Buttons where the first visibleButtonsCount buttons render inline and the rest collapse into an overflow ("more") dropdown menu.

When to use

Use ButtonList for a set of related actions that should degrade gracefully when there are too many to show at once — the overflow ones move into a dropdown triggered by an ellipsis button. Set visibleButtonsCount to how many stay inline (use 0 to put everything in the menu).

For a small, fixed set of buttons joined into one segmented control, use ButtonGroup instead.
Renders nothing when buttons is empty.

There is no @uxf/form twin — this is a layout component, not a form field.

Usage

import { ButtonList } from "@uxf/ui/button-list";

// all four inline
<ButtonList
    buttons={[
        { label: "First item" },
        { label: "Second item" },
        { label: "Third item" },
        { label: "Fourth item" },
    ]}
    variant="secondary"
    visibleButtonsCount={4}
/>

// one inline, the rest in an overflow dropdown
<ButtonList
    buttons={[
        { icon: "check", label: "First item", onClick: console.log },
        { icon: "user", label: "Second item", color: "positive" },
        { icon: "cloud", label: "Third item" },
        { icon: "xmarkLarge", label: "Fourth item", onClick: console.log },
    ]}
    openButton={{ color: "default", variant: "secondary" }}
    size="sm"
    variant="secondary"
    visibleButtonsCount={1}
/>;

Props

Prop	Type	Default	Description
`buttons`	`SingleButtonProps[]`	—	Required. Buttons to render. See the item shape below.
`visibleButtonsCount`	`number`	—	Required. How many buttons stay inline; the remainder collapse into the overflow menu.
`openButton`	`SingleButtonProps`	—	Config for the overflow trigger. Defaults to an icon-only button with the `ellipsis-vertical` icon; set `icon: null` to hide the icon.
`color`	`ButtonProps["color"]`	—	Default color for every button (a per-button `color` overrides it).
`size`	`ButtonProps["size"]`	—	Default size for every button (a per-button `size` overrides it).
`variant`	`ButtonProps["variant"]`	—	Default variant for every button (a per-button `variant` overrides it).
`className`	`string`	—	Extra class on the list wrapper `<div>`.
`classNameDropdown`	`string`	—	Extra class on the overflow menu container.
`menuMaxHeight`	`number`	`240`	Max height of the overflow menu, in px (clamped to the available viewport height).
`menuPlacement`	`Placement`	`"bottom-start"`	Overflow menu placement (from `@floating-ui/react`).
`menuStrategy`	`Strategy`	—	Overflow menu positioning strategy (from `@floating-ui/react`).

Each buttons / openButton item is Omit<ButtonProps, "children"> plus:

Key	Type	Description
`label`	`ReactNode`	Button text (rendered next to the icon).
`icon`	`IconName \| null`	Optional leading icon.

Variants & states

color, size and variant accept the same values as Button and act as list-wide defaults; any value set on an individual buttons item wins. Per-button states such as isDisabled are supported and also disable the corresponding entry in the overflow menu.

Requirements

Import the component stylesheet once in your global CSS, together with the Button stylesheet:

@import url("@uxf/ui/css/button.css");
@import url("@uxf/ui/css/button-list.css");

Also requires the global @uxf/ui token layer, set up once per app — see @uxf/ui setup.

The overflow menu is an interactive dropdown built on @headlessui/react and @floating-ui/react and relies on React hooks, so render ButtonList within a client component.

Default

Open in new tab

When to use

For a small, fixed set of buttons joined into one segmented control, use ButtonGroup instead.

Renders nothing when buttons is empty.

There is no @uxf/form twin — this is a layout component, not a form field.

Usage

import { ButtonList } from "@uxf/ui/button-list"; // all four inline <ButtonList buttons={[ { label: "First item" }, { label: "Second item" }, { label: "Third item" }, { label: "Fourth item" }, ]} variant="secondary" visibleButtonsCount={4} /> // one inline, the rest in an overflow dropdown <ButtonList buttons={[ { icon: "check", label: "First item", onClick: console.log }, { icon: "user", label: "Second item", color: "positive" }, { icon: "cloud", label: "Third item" }, { icon: "xmarkLarge", label: "Fourth item", onClick: console.log }, ]} openButton={{ color: "default", variant: "secondary" }} size="sm" variant="secondary" visibleButtonsCount={1} />;

Props

Prop

Type

Default

Description

buttons

SingleButtonProps[]

—

Required. Buttons to render. See the item shape below.

visibleButtonsCount

number

—

Required. How many buttons stay inline; the remainder collapse into the overflow menu.

openButton

SingleButtonProps

—

Config for the overflow trigger. Defaults to an icon-only button with the ellipsis-vertical icon; set icon: null to hide the icon.

color

ButtonProps["color"]

—

Default color for every button (a per-button color overrides it).

size

ButtonProps["size"]

—

Default size for every button (a per-button size overrides it).

variant

ButtonProps["variant"]

—

Default variant for every button (a per-button variant overrides it).

className

string

—

Extra class on the list wrapper <div>.

classNameDropdown

string

—

Extra class on the overflow menu container.

menuMaxHeight

number

240

Max height of the overflow menu, in px (clamped to the available viewport height).

menuPlacement

Placement

"bottom-start"

Overflow menu placement (from @floating-ui/react).

menuStrategy

Strategy

—

Overflow menu positioning strategy (from @floating-ui/react).

Each buttons / openButton item is Omit<ButtonProps, "children"> plus:

Key

Type

Description

label

ReactNode

Button text (rendered next to the icon).

icon

IconName | null

Optional leading icon.

Requirements

Import the component stylesheet once in your global CSS, together with the Button stylesheet:

@import url("@uxf/ui/css/button.css"); @import url("@uxf/ui/css/button-list.css");

Also requires the global @uxf/ui token layer, set up once per app — see @uxf/ui setup.

The overflow menu is an interactive dropdown built on @headlessui/react and @floating-ui/react and relies on React hooks, so render ButtonList within a client component.