Preview
import { Button } from "@/components/ui/button";
<Button size="md" variant="primary">Save changes</Button>import { Button } from "@primitiv-ui/react";
<Button>Save changes</Button>Density is set by a data-density ancestor — the Context system, not a Button prop.
npx primitiv add buttonpnpm dlx primitiv add buttonyarn dlx primitiv add buttonbunx primitiv add buttonImport
import { Button } from "@/components/ui/button";Copied into your project as .primitiv-button — you own the file afterwards, so upgrades are opt-in.
Headless mode installs the npm package instead: @primitiv-ui/react
Extends HTMLButtonElement — every native attribute of that element is accepted and forwarded.
| Prop | Type | Default | From | Description |
|---|---|---|---|---|
| asChild | boolean | false | headless | Renders the child element instead of a native <button>, merging all
props — aria-, data-, event handlers, ref — onto it via
Slot. type is not forwarded in this mode; the child owns its
own type semantics. See the asChild example on Button. |
| children | ReactNode | — | headless | Button content. Under asChild, becomes the single child element Slot merges props onto. |
| ref | Ref<HTMLButtonElement> | — | headless | Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
Forwarded to the underlying HTMLButtonElement, or — under
asChild — merged onto the rendered child via Slot. |
| type | "button" | "submit" | "reset" | "button" | headless | The button's native type attribute, restricted to the three valid
values. Defaults to "button" (not the DOM's own default of
"submit"), so a Button placed inside a <form> never triggers an
accidental submit unless set explicitly. |
| variant | "primary" | "secondary" | "danger" | "ghost" | "link" | primary | styled | Visual intent / emphasis. |
| size | "xs" | "sm" | "md" | "lg" | "xl" | md | styled | Control size; data-density scales each size further. |
--primitiv-button-bg--primitiv-button-fg--primitiv-button-border-color--primitiv-button-border-width--primitiv-button-radius--primitiv-button-height--primitiv-button-padding-inline--primitiv-button-gap--primitiv-button-icon-size--primitiv-button-icon-optical-inset--primitiv-button-font-family--primitiv-button-font-size--primitiv-button-font-weight--primitiv-button-line-height--primitiv-button-shadowclassName: .primitiv-button
| Attribute | Value | When |
|---|---|---|
data-disabled | "" | disabled |
| Attribute | Value | When |
|---|---|---|
data-disabled | "" | disabled |
<button> behaviour, kept rather than re-implemented.:focus-visible, so it appears for keyboard users and not on mouse click.disabled exposes both the native attribute and data-disabled, so pointer events stop and assistive tech reports the state.asChild the a11y wiring transfers to the element you supply, so a rendered <a> keeps role="link" rather than being announced as a button.Five intents. primary carries the main action on a view; link reads as text so it keeps the button's hit area and focus ring.
import { Button } from "@/components/ui/button";
<div data-density="comfortable"> <Button variant="primary">Primary</Button> <Button variant="secondary">Secondary</Button> <Button variant="danger">Danger</Button> <Button variant="ghost">Ghost</Button> <Button variant="link">Link</Button></div>import { Button } from "@primitiv-ui/react";
// `variant`: styled-layer contract, absent from the headless primitive// — so the class names below are yours to define.
<div data-density="comfortable"> <Button className="btn-primary">Primary</Button> <Button className="btn-secondary">Secondary</Button> <Button className="btn-danger">Danger</Button> <Button className="btn-ghost">Ghost</Button> <Button className="btn-link">Link</Button></div>Five sizes — and every one rescales again with the nearest data-density ancestor. Change the density above and watch the whole ramp shift: that is the Context system, not a Button prop.
import { Button } from "@/components/ui/button";
<div data-density="comfortable"> <Button size="xs">Button xs</Button> <Button size="sm">Button sm</Button> <Button size="md">Button md</Button> <Button size="lg">Button lg</Button> <Button size="xl">Button xl</Button></div>import { Button } from "@primitiv-ui/react";
// `size`: styled-layer contract, absent from the headless primitive// — so the class names below are yours to define.
<div data-density="comfortable"> <Button className="btn-xs">Button xs</Button> <Button className="btn-sm">Button sm</Button> <Button className="btn-md">Button md</Button> <Button className="btn-lg">Button lg</Button> <Button className="btn-xl">Button xl</Button></div>Icons are children, not props, so a leading or trailing glyph is just composition — nothing to configure.
import { Button } from "@/components/ui/button";import { ArrowRight, Plus } from "@primitiv-ui/icons";
<Button> <Plus /> Add item</Button>
<Button variant="secondary"> Continue <ArrowRight /></Button>import { Button } from "@primitiv-ui/react";import { ArrowRight, Plus } from "@primitiv-ui/icons";
<Button> <Plus /> Add item</Button>
<Button> Continue <ArrowRight /></Button>asChild renders your own element instead of a <button> — here a Next <Link> — merging the button props and styles onto it. The a11y wiring follows, so it stays role="link".
import Link from "next/link";import { Button } from "@/components/ui/button";import { ArrowRight } from "@primitiv-ui/icons";
<Button asChild> <Link href="/components"> View the docs <ArrowRight /> </Link></Button>import Link from "next/link";import { Button } from "@primitiv-ui/react";import { ArrowRight } from "@primitiv-ui/icons";
<Button asChild> <Link href="/components"> View the docs <ArrowRight /> </Link></Button>disabled sets the native attribute and exposes data-disabled, so pointer events stop and the focus ring is suppressed — no ARIA needed, because the real attribute is doing the work.
import { Button } from "@/components/ui/button";
<Button disabled>Save changes</Button><Button variant="secondary" disabled>Cancel</Button>import { Button } from "@primitiv-ui/react";
<Button disabled>Save changes</Button><Button disabled>Cancel</Button>