Button

A button for actions, with styles that a link can reuse.

import { Button } from "@/components/ui/button"

export default function ButtonDemo() {
  return <Button>Button</Button>
}

Installation

pnpm dlx shadcn@latest add @arene/button

Needs the arene setup first.

Usage

import { Button } from "@/components/ui/button"
<Button variant="outline">Button</Button>

Variants

Pick a style with variant. default is the primary action. outline is the raised neutral key for everyday actions, Cancel and Close among them. secondary is a flat grey fill for actions that should stay quiet, and ghost has no fill until it is hovered.

import { Button } from "@/components/ui/button"
import { HStack } from "@/components/ui/stack"

export default function ButtonVariants() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Button variant="default">Default</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="destructive">Destructive</Button>
      <Button variant="link">Link</Button>
    </HStack>
  )
}

Size

size sets the button's height and padding.

import { Button } from "@/components/ui/button"
import { HStack } from "@/components/ui/stack"

export default function ButtonSize() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Button size="xs">Extra small</Button>
      <Button size="sm">Small</Button>
      <Button size="default">Default</Button>
      <Button size="lg">Large</Button>
    </HStack>
  )
}

Icon

Use an icon-* size for a square button. Always give an icon-only button an aria-label. There is no text for a screen reader to announce.

import { Button } from "@/components/ui/button"
import { HStack } from "@/components/ui/stack"
import { PlusIcon } from "@phosphor-icons/react/dist/csr/Plus"

export default function ButtonIcon() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Button size="icon-xs" variant="outline" aria-label="Add">
        <PlusIcon aria-hidden="true" />
      </Button>
      <Button size="icon-sm" variant="outline" aria-label="Add">
        <PlusIcon aria-hidden="true" />
      </Button>
      <Button size="icon" variant="outline" aria-label="Add">
        <PlusIcon aria-hidden="true" />
      </Button>
      <Button size="icon-lg" variant="outline" aria-label="Add">
        <PlusIcon aria-hidden="true" />
      </Button>
    </HStack>
  )
}

With icon

Set iconPosition to the side the icon is on, so the button tightens its padding there.

import { Button } from "@/components/ui/button"
import { HStack } from "@/components/ui/stack"
import { ArrowRightIcon } from "@phosphor-icons/react/dist/csr/ArrowRight"
import { GitBranchIcon } from "@phosphor-icons/react/dist/csr/GitBranch"

export default function ButtonWithIcon() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Button variant="outline" iconPosition="start">
        <GitBranchIcon aria-hidden="true" />
        New branch
      </Button>
      <Button iconPosition="end">
        Continue
        <ArrowRightIcon aria-hidden="true" />
      </Button>
    </HStack>
  )
}

Without iconPosition the padding stays symmetric and the icon looks inset. StyleX has no :has(), so the button has to be told which side the icon is on.

Loading

Render a Spinner with iconPosition="start" and set disabled while the action is in flight.

import { Button } from "@/components/ui/button"
import { Spinner } from "@/components/ui/spinner"
import { HStack } from "@/components/ui/stack"

export default function ButtonLoading() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Button disabled iconPosition="start">
        <Spinner aria-hidden="true" />
        Deploying
      </Button>
      <Button variant="outline" disabled>
        Disabled
      </Button>
    </HStack>
  )
}

Rounded

Pass an xstyle with borderRadius: radius.full for a pill.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { HStack } from "@/components/ui/stack"
import { radius } from "@/theme/tokens.stylex"
import { ArrowUpIcon } from "@phosphor-icons/react/dist/csr/ArrowUp"

const styles = stylex.create({
  pill: { borderRadius: radius.full },
})

export default function ButtonRounded() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Button xstyle={styles.pill}>Rounded</Button>
      <Button variant="outline" xstyle={styles.pill}>
        Rounded
      </Button>
      <Button size="icon" xstyle={styles.pill} aria-label="Send">
        <ArrowUpIcon aria-hidden="true" />
      </Button>
    </HStack>
  )
}

Pressed

The raised variants, default, outline and destructive, shrink slightly while pressed. secondary and ghost are flat and do not change. The rule is inside @media (hover: hover), so it does not apply on touch screens. A button inside a ButtonGroup does not shrink either.

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"
import { HStack } from "@/components/ui/stack"

export default function ButtonPressed() {
  return (
    <HStack align="center" gap={4} wrap="wrap">
      <Button>Press me</Button>
      <Button variant="outline">Press me</Button>
      <ButtonGroup aria-label="No press feedback">
        <Button variant="outline">Grouped</Button>
        <Button variant="outline">Grouped</Button>
      </ButtonGroup>
    </HStack>
  )
}

Spread the buttonStyles maps onto an anchor.

Do not use <Button render={<a />} /> for links. Base UI's Button always applies role="button", which overrides the link role. Open-in-new-tab and middle click stop working, and a screen reader announces a button.

import * as stylex from "@stylexjs/stylex"
import { clsx } from "clsx"
import { buttonStyles } from "@/components/ui/button"
import { ArrowSquareOutIcon } from "@phosphor-icons/react/dist/csr/ArrowSquareOut"

const sx = stylex.props(
  buttonStyles.base,
  buttonStyles.variants.outline,
  buttonStyles.sizes.default,
  buttonStyles.iconEnd.default,
)

export default function ButtonAsLink() {
  return (
    <a
      href="https://base-ui.com"
      target="_blank"
      rel="noopener noreferrer"
      data-variant="outline"
      {...sx}
      className={clsx("arene-icons", sx.className)}
    >
      Base UI
      <ArrowSquareOutIcon aria-hidden="true" />
    </a>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Button

Wraps Base UI's Button and accepts every prop it does, render and nativeButton among them.

PropTypeDefault
variant"default" | "outline" | "secondary" | "ghost" | "destructive" | "link""default"
size"default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg""default"
iconPosition"start" | "end" | "both"—
xstyleStyleXStyles—
styleCSSProperties—
classNamestring—

xstyle is merged last, so it beats the variant and the size. className is concatenated with no conflict resolution. Use it for plain-CSS hooks.

buttonStyles

The style maps behind Button. Spread them onto any element:

import * as stylex from "@stylexjs/stylex"
import { buttonStyles } from "@/components/ui/button"
import { clsx } from "clsx"

const sx = stylex.props(buttonStyles.base, buttonStyles.variants.outline, buttonStyles.sizes.sm)

;<a href="/docs" data-variant="outline" {...sx} className={clsx("arene-icons", sx.className)} />

Merge className from the stylex.props() result by hand. A second className attribute beside the spread replaces it.

KeyWhat it is
baseShape, type and disabled state, with the shared focus ring
variantsOne namespace per variant, including hover styles
sizesOne namespace per size
iconStartLeading-icon padding, keyed by size
iconEndTrailing-icon padding, keyed by size
pressableThe 1px press, applied by Button to a lone raised variant
glossThe sheen and reflection line, applied to default and destructive
groupInner-edge radii and shared borders, keyed by group orientation

base is two styles, the button's own and the shared states.focusRing. Set a border of your own through --arene-border-color rather than borderColor. A flat borderColor replaces the property with all of its conditions, so the ring loses its focus colour. That is why the outline variant sets the variable.

Keep the arene-icons class and the data-variant attribute. interop.css sizes icons off the class and styles an open menu trigger off the attribute.

ButtonGroupContext

The context a ButtonGroup provides and Button reads. It holds the group's orientation. It is exported so a component built from buttonStyles can join a group too.

Data attributes

AttributeOnEffect
data-slot="button"the buttonTargets the button from a parent
data-variantthe buttonPicks the background the button holds while its menu is open
data-sizethe buttonReflects the size prop, for styling from a parent

interop.css sizes icons only inside the arene-icons class. Without it a child <svg> keeps its own size, which defaults to 1em for a Phosphor icon.