## Overview [#overview]
The **Button** component provides a versatile and customizable button system with multiple variants, appearances, sizes, and shapes. It supports polymorphic rendering with the `render` prop (Base UI pattern), as well as special features like pending states and URL state management.
Use `Button.Wrapper` to visually attach adjacent buttons for split-button layouts while keeping each inner action as a real `Button`.
## Usage [#usage]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
```
```tsx
```
Using Cubitt's URL-state hooks, you can sync button clicks with the URL by providing `paramName` and `paramSetValue`:
```tsx
// Clicking sets ?action=save in the URL
// Advanced options:
```
Use the `render` prop to render the button as a different element while preserving button styling:
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
import { Link } from "@tanstack/react-router";
}>Go Home;
```
## Examples [#examples]
### Secondary [#secondary]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return ;
}
```
### Frost [#frost]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return ;
}
```
### Destructive [#destructive]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return ;
}
```
### Outline [#outline]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return ;
}
```
### Ghost [#ghost]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return ;
}
```
### With Icon [#with-icon]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
import {
UserPen } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Component() {
return (
);
}
```
### Icon Only [#icon-only]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
import {
UserPen } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Component() {
return (
);
}
```
### Pending [#pending]
Shows a loading spinner while an action is in progress.
```tsx
"use client";
import { Button } from "@tilt-legal/cubitt-components/primitives";
import { useEffect, useState } from "react";
export default function Component() {
const [isPending, setIsPending] = useState(false);
useEffect(() => {
if (!isPending) {
return;
}
const timeout = window.setTimeout(() => {
setIsPending(false);
}, 2000);
return () => window.clearTimeout(timeout);
}, [isPending]);
return (
);
}
```
### With Badge [#with-badge]
Combine buttons with badges for notifications and counters.
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
import {
Bell,
Inbox,
CircleCheck } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Component() {
return (
);
}
```
### Sizes [#sizes]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
import {
UserPen } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Component() {
return (
);
}
```
### Link [#link]
Style buttons as links using `variant="link"`.
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
import { Link } from "@tanstack/react-router";
export default function Component() {
return (
}>
Link Button
}>
Link Button
}>
Link Button
);
}
```
### Split Button [#split-button]
Use `Button.Wrapper` when you want a primary action and an adjacent secondary trigger to read as a single control.
```tsx
"use client";
import {
Button,
Menu,
MenuContent,
MenuItem,
MenuSeparator,
MenuTrigger,
} from "@tilt-legal/cubitt-components/primitives";
import { useEffect, useState } from "react";
export default function Component() {
const PENDING_RESET_DELAY_MS = 2000;
const variants = [
{ label: "Default", moreLabel: "More primary actions", variant: "default" },
{ label: "Secondary", moreLabel: "More secondary actions", variant: "secondary" },
{ label: "Destructive", moreLabel: "More destructive actions", variant: "destructive" },
{ label: "Frost", moreLabel: "More frost actions", variant: "frost" },
{ label: "Outline", moreLabel: "More outline actions", variant: "outline" },
] as const;
function SplitButtonItem({
label,
moreLabel,
variant,
}: (typeof variants)[number]) {
const [isPending, setIsPending] = useState(false);
useEffect(() => {
if (!isPending) {
return;
}
const timeout = window.setTimeout(() => {
setIsPending(false);
}, PENDING_RESET_DELAY_MS);
return () => window.clearTimeout(timeout);
}, [isPending]);
return (
);
}
return (
{variants.map((item) => (
))}
);
}
```
### Disabled [#disabled]
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
### URL State [#url-state]
Sync button clicks with URL parameters. Click a button to see the URL update with the corresponding action.
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
## API Reference [#api-reference]
### Button [#button]
The root component for creating buttons with multiple variants, appearances, sizes, and shapes. Supports polymorphic rendering via the `render` prop and URL state management.
#### URL State Props [#url-state-props]
When provided with a `paramName`, the button will set URL parameters when clicked.