Skip to content
Shaken UI
Sign in

Button Group

Save

Joins buttons into one control with shared hairline borders, horizontally or vertically, with text segments and split buttons.

Category
Layout
Version
0.1.0
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Button Group preview
3 retries

Installation

npx @shakenui/cli add button-group

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add button-group --dry-run

Usage

button-group-example.tsx
"use client";

import { useState } from "react";
import { Button } from "@/components/shaken/ui/button";
import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@/components/shaken/ui/button-group";
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "@/components/shaken/ui/dropdown-menu";

const icon = { "aria-hidden": true, viewBox: "0 0 16 16", fill: "none" } as const;
const stroke = { stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round" } as const;

const mergeMethods = ["Squash and merge", "Rebase and merge", "Create a merge commit"] as const;

export default function ButtonGroupExample() {
  const [method, setMethod] = useState<(typeof mergeMethods)[number]>("Squash and merge");
  const [retries, setRetries] = useState(3);

  return (
    <div className="flex flex-wrap items-start justify-center gap-x-10 gap-y-8">
      <div className="flex flex-col items-start gap-6">
        <ButtonGroup aria-label="Artifact actions">
          <Button variant="secondary">
            <svg {...icon}>
              <rect x="5.5" y="5.5" width="8" height="8" rx="1.5" {...stroke} />
              <path d="M10.5 3.5v-.25a.75.75 0 0 0-.75-.75h-6.5a.75.75 0 0 0-.75.75v6.5c0 .41.34.75.75.75h.25" {...stroke} />
            </svg>
            Copy
          </Button>
          <Button variant="secondary">
            <svg {...icon}>
              <path d="M8 2.5v7.5M4.75 7 8 10.25 11.25 7M3 13.5h10" {...stroke} />
            </svg>
            Download
          </Button>
          <Button variant="secondary">
            <svg {...icon}>
              <path d="M9.5 2.5h4v4M13.5 2.5 8 8M11.5 9.5v3a1 1 0 0 1-1 1h-7a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1h3" {...stroke} />
            </svg>
            Open
          </Button>
        </ButtonGroup>

        <ButtonGroup aria-label="Merge pull request">
          <Button>{method}</Button>
          <ButtonGroupSeparator />
          <DropdownMenu>
            <DropdownMenuTrigger render={<Button aria-label="Choose merge method" className="w-9 px-0!" />}>
              <svg {...icon}>
                <path d="m4.5 6.25 3.5 3.5 3.5-3.5" {...stroke} />
              </svg>
            </DropdownMenuTrigger>
            <DropdownMenuContent align="end">
              {mergeMethods.map((option) => (
                <DropdownMenuItem key={option} onClick={() => setMethod(option)}>
                  <svg {...icon} className={option === method ? "" : "invisible"}>
                    <path d="m3.75 8.25 2.75 2.75 5.75-6" {...stroke} />
                  </svg>
                  {option}
                </DropdownMenuItem>
              ))}
            </DropdownMenuContent>
          </DropdownMenu>
        </ButtonGroup>

        <ButtonGroup aria-label="Retry limit">
          <Button variant="secondary" aria-label="Fewer retries" className="w-9 px-0!" disabled={retries === 0} onClick={() => setRetries(retries - 1)}>
            <svg {...icon}>
              <path d="M3.5 8h9" {...stroke} />
            </svg>
          </Button>
          <ButtonGroupText aria-live="polite" className="min-w-24 justify-center text-zinc-950 tabular-nums dark:text-white">
            {retries} {retries === 1 ? "retry" : "retries"}
          </ButtonGroupText>
          <Button variant="secondary" aria-label="More retries" className="w-9 px-0!" disabled={retries === 5} onClick={() => setRetries(retries + 1)}>
            <svg {...icon}>
              <path d="M8 3.5v9M3.5 8h9" {...stroke} />
            </svg>
          </Button>
        </ButtonGroup>
      </div>

      <ButtonGroup orientation="vertical" aria-label="Canvas zoom">
        <Button variant="secondary" aria-label="Zoom in" className="w-9 px-0!">
          <svg {...icon}>
            <path d="M8 3.5v9M3.5 8h9" {...stroke} />
          </svg>
        </Button>
        <Button variant="secondary" aria-label="Zoom out" className="w-9 px-0!">
          <svg {...icon}>
            <path d="M3.5 8h9" {...stroke} />
          </svg>
        </Button>
        <Button variant="secondary" aria-label="Fit to view" className="w-9 px-0!">
          <svg {...icon}>
            <path d="M2.75 6V3.75a1 1 0 0 1 1-1H6M10 2.75h2.25a1 1 0 0 1 1 1V6M13.25 10v2.25a1 1 0 0 1-1 1H10M6 13.25H3.75a1 1 0 0 1-1-1V10" {...stroke} />
          </svg>
        </Button>
      </ButtonGroup>
    </div>
  );
}

API

PropTypeDefaultDescription
orientation"horizontal" | "vertical""horizontal"Lays segments out in a row or a column.
aria-labelstring—Names the group, for example "Artifact actions".
ButtonGroupSeparatorComponentProps<"div">—A hairline between filled segments, such as the two halves of a primary split button.
ButtonGroupTextComponentProps<"div">—A static segment for a label, unit, value, or prefix, bordered like a secondary button.

Accessibility

  • Renders role="group"; give it an aria-label so screen readers announce what its buttons act on.
  • Segments keep their own focus rings; the focused or hovered segment is raised above its neighbours so its full outline and border show.
  • Icon-only segments need an aria-label (the example labels Zoom in, Zoom out, and Fit to view).
  • In a split button the arrow is a separate menu button with its own name ("Choose merge method"), aria-haspopup, and aria-expanded.
  • The press scale is turned off inside a group so a pressed segment never opens a gap in the shared edge; hover and press are shown with color.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/ui/button-group.tsxbutton-group
  • Also installs button@0.2.1registry dependency
  • Also installs dropdown-menu@0.2.1registry dependency
  • npm packages: noneReact and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/button-group/0.1.0.json.

ui/button-group.tsxShow
ui/button-group.tsx
import type { ComponentProps } from "react";

function cx(...classes: (string | false | null | undefined)[]) {
  return classes.filter(Boolean).join(" ");
}

// Every direct child joins the group: inner corners square off and each segment overlaps the
// previous one by 1px, so neighbouring hairlines merge into one. The first and last segments are
// counted with `nth-child(… of …)`, skipping the hidden focus guards a menu or popover inserts
// beside its trigger while open. Class names are written out in full so Tailwind can find them.
const orientations = {
  horizontal: cx(
    "flex-row [&>*]:rounded-none",
    "[&>:nth-child(1_of_:not([data-base-ui-focus-guard],[aria-owns]))]:rounded-l-lg",
    "[&>:nth-last-child(1_of_:not([data-base-ui-focus-guard],[aria-owns]))]:rounded-r-lg",
    "[&>*:not(:first-child)]:-ml-px",
  ),
  vertical: cx(
    "flex-col [&>*]:rounded-none",
    "[&>:nth-child(1_of_:not([data-base-ui-focus-guard],[aria-owns]))]:rounded-t-lg",
    "[&>:nth-last-child(1_of_:not([data-base-ui-focus-guard],[aria-owns]))]:rounded-b-lg",
    "[&>*:not(:first-child)]:-mt-px",
  ),
} as const;

export type ButtonGroupOrientation = keyof typeof orientations;

export interface ButtonGroupProps extends ComponentProps<"div"> {
  /** Lays the segments out in a row or a column. */
  orientation?: ButtonGroupOrientation;
}

/**
 * Joins buttons (and inputs or `ButtonGroupText`) into one control that shares its borders.
 * Name the group with `aria-label` so screen readers announce what the buttons act on.
 * Segments keep their own hover and focus styles; the hovered or focused one is lifted above its
 * neighbours so its full border and focus ring show. The press scale is turned off inside a group,
 * since shrinking one segment would open a gap in the shared edge.
 */
export function ButtonGroup({ orientation = "horizontal", className, ...props }: ButtonGroupProps) {
  return (
    <div
      role="group"
      data-orientation={orientation}
      className={cx(
        "inline-flex w-fit items-stretch isolate",
        orientations[orientation],
        "[&>*]:relative [&>*:hover]:z-10 [&>*:focus-visible]:z-20 [&>*:focus-within]:z-20 [&>*:active]:scale-100!",
        className,
      )}
      {...props}
    />
  );
}

/**
 * A hairline between two filled segments, such as the label and the arrow of a primary split
 * button. Bordered (secondary) segments already share an edge and do not need one.
 */
export function ButtonGroupSeparator({ className, ...props }: ComponentProps<"div">) {
  return (
    <div
      aria-hidden="true"
      data-slot="button-group-separator"
      className={cx(
        "z-30 shrink-0 self-stretch bg-white/25 dark:bg-black/20",
        "in-data-[orientation=horizontal]:w-px in-data-[orientation=vertical]:h-px",
        className,
      )}
      {...props}
    />
  );
}

/**
 * A static segment for a label, unit, or prefix, such as "https://" before an input.
 * Matches the secondary button's hairline so it sits flush with bordered segments.
 */
export function ButtonGroupText({ className, ...props }: ComponentProps<"div">) {
  return (
    <div
      className={cx(
        "inline-flex items-center gap-2 border border-zinc-950/12 px-3 text-sm whitespace-nowrap text-zinc-500 select-none",
        "dark:border-white/15 dark:text-zinc-400 [&_svg]:size-4 [&_svg]:shrink-0",
        className,
      )}
      {...props}
    />
  );
}