Button

A clickable button for actions, in a range of styles and sizes.

Usage

import { Button } from '@appica/ui-react/button'

<Button>Click me</Button>

Examples

Variants

The variant prop sets the visual style. light is meant for dark or image backgrounds and is omitted below.

import { Button } from '@appica/ui-react/button'

const variants = ['primary', 'primary-outline', 'secondary', 'soft', 'outline', 'ghost', 'destructive'] as const

const label = (variant: string) =>
  variant
    .split('-')
    .map((word) => word[0]!.toUpperCase() + word.slice(1))
    .join(' ')

export default function ButtonVariants() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {variants.map((variant) => (
        <Button key={variant} variant={variant}>
          {label(variant)}
        </Button>
      ))}
    </div>
  )
}

Sizes

import { Button } from '@appica/ui-react/button'

export default function ButtonSizes() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  )
}

With an icon

Mark an icon with data-icon="start" or data-icon="end" so the button reserves the right inner spacing. Use an icon-* size for an icon-only button, and always give it an aria-label.

import { Button } from '@appica/ui-react/button'
import { Download, ArrowUpRight, Bookmark } from '@appica/icons-react'

export default function ButtonWithIcon() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Button variant="secondary">
        <Download data-icon="start" />
        Download
      </Button>
      <Button variant="outline">
        Open
        <ArrowUpRight data-icon="end" />
      </Button>
      <Button size="icon-md" variant="soft" aria-label="Bookmark">
        <Bookmark />
      </Button>
    </div>
  )
}

Loading state

While an action is in flight, set disabled to block further clicks and swap the label to a Spinner. Add focusableWhenDisabled so focus stays on the button when it becomes disabled — without it, focus would jump to the body. Give the Spinner currentColor so it inherits the button's text color, and data-icon="start" so it gets the same inner spacing as an icon.

'use client'

import * as React from 'react'
import { Button } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'

export default function ButtonLoading() {
  const [loading, setLoading] = React.useState(false)

  return (
    <Button
      disabled={loading}
      focusableWhenDisabled
      onClick={() => {
        setLoading(true)
        setTimeout(() => setLoading(false), 3000)
      }}
    >
      {loading && <Spinner variant="dots" currentColor data-icon="start" className="text-[1.125rem]" />}
      {loading ? 'Submitting' : 'Submit'}
    </Button>
  )
}

As a link

A link should stay a link. To make an <a> (or your router's <Link>) merely look like a button, apply the exported buttonVariants classes to it directly — don't render it through Button. See Composition → Links that look like a button.

import { buttonVariants } from '@appica/ui-react/button'
import { ArrowUpRight } from '@appica/icons-react'

export default function ButtonAsLink() {
  return (
    <a
      href="https://base-ui.com"
      target="_blank"
      rel="noreferrer"
      className={buttonVariants({ variant: 'soft', size: 'md' })}
    >
      Visit Base UI
      <ArrowUpRight data-icon="end" />
    </a>
  )
}

Don't render a link through Button

Rendering an <a> through Button forces button semantics onto a link, which misleads assistive tech — use buttonVariants on the link instead. The render prop with nativeButton={false} is only for rendering as a non-interactive element (a <div> / <span>) where you still want button behavior.

// render is for adopting a different element while KEEPING button semantics — e.g. a <div>:
<Button render={<div />} nativeButton={false}>
  Not a native button
</Button>

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

For setup details and caveats, see the RTL guide.

API reference

Button wraps Base UI's Button and passes every remaining prop (onClick, type, aria-*, ref, …) straight through, so anything the Base UI primitive accepts works here — see its docs for the full API. Inside a ButtonGroup, variant and size are inherited from the group unless set on the button.

Prop	Type	Default	Description
`variant`	`'primary' \| 'primary-outline' \| 'secondary' \| 'soft' \| 'outline' \| 'ghost' \| 'destructive' \| 'light'`	`'primary'`	Visual style.
`size`	`'sm' \| 'md' \| 'lg' \| 'icon-sm' \| 'icon-md' \| 'icon-lg'`	`'md'`	Height and padding. The `icon-*` sizes are square, for icon-only buttons.
`disabled`	`boolean`	`false`	Disables interaction; sets `data-disabled` for styling.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the button's HTML element with a different tag, or compose it with another component.
`nativeButton`	`boolean`	`true`	Whether the rendered element is a native `<button>`. Set `false` when `render`ing a non-button (link).
`className`	`string`	—	Extra classes, merged after the variant classes via `tailwind-merge`.

Accessibility

Renders a native <button> (or whatever you pass to render), so it is focusable and in the tab order by default.
Enter and Space activate the button.
disabled removes the button from the tab order and sets data-disabled for styling; the pointer is disabled via pointer-events-none.
Icon-only buttons have no text, so give them an aria-label.
All press and hover transitions are wrapped in motion-reduce: variants, so they are skipped when the user prefers reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback