Button

Displays a button or a component that looks like a button.

import { ilha } from "ilha";
import { Plus } from "lucide";
import { Button, Icon } from "areia";

export default ilha.render(() => (
  <div class="flex flex-wrap items-center gap-2">
    <Button variant="secondary">Button</Button>
    <Button
      variant="secondary"
      shape="square"
      icon={<Icon icon={Plus} />}
      aria-label="Add"
    />
  </div>
));

Import

import { Button, ButtonGroup } from "areia";

Usage

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="secondary">Click me</Button>
));

Examples

Variants

Primary

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="primary">Primary</Button>
));

Secondary

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="secondary">Secondary</Button>
));

Ghost

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="ghost">Ghost</Button>
));

Destructive

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="destructive">Destructive</Button>
));

Outline

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="outline">Outline</Button>
));

Secondary Destructive

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="secondary-destructive">
    Secondary Destructive
  </Button>
));

Sizes

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <div class="flex flex-wrap items-center gap-3">
    <Button size="xs" variant="secondary">
      Extra Small
    </Button>
    <Button size="sm" variant="secondary">
      Small
    </Button>
    <Button size="base" variant="secondary">
      Base
    </Button>
    <Button size="lg" variant="secondary">
      Large
    </Button>
  </div>
));

With Icon

import { ilha } from "ilha";
import { Plus } from "lucide";
import { Button, Icon } from "areia";

export default ilha.render(() => (
  <Button variant="secondary" icon={<Icon icon={Plus} />}>
    Create Ilha app
  </Button>
));

For icon-only buttons, use shape="square" or shape="circle" with the icon prop. Always include aria-label for accessibility — without visible text, screen readers need the label to convey the button’s purpose.

import { ilha } from "ilha";
import { Plus } from "lucide";
import { Button, Icon } from "areia";

export default ilha.render(() => (
  <div class="flex flex-wrap items-center gap-3">
    <Button
      variant="secondary"
      shape="square"
      icon={<Icon icon={Plus} />}
      aria-label="Add item"
    />
    <Button
      variant="secondary"
      shape="circle"
      icon={<Icon icon={Plus} />}
      aria-label="Add item"
    />
  </div>
));

Loading State

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="primary" loading>
    Loading...
  </Button>
));

Disabled State

import { ilha } from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="secondary" disabled>
    Disabled
  </Button>
));

Title

Use the native title attribute when additional context helps the user understand the action.

import { ilha } from "ilha";
import { Plus } from "lucide";
import { Button, Icon } from "areia";

export default ilha.render(() => (
  <div class="flex flex-wrap items-center gap-3">
    <Button variant="secondary" title="Create a new Ilha app">
      Create Ilha app
    </Button>
    <Button
      variant="secondary"
      shape="square"
      icon={<Icon icon={Plus} />}
      aria-label="Add item"
      title="Add item"
    />
  </div>
));

Button Group

Use ButtonGroup to visually join related buttons or controls.

import { ilha } from "ilha";
import { Bold, Italic, Underline } from "lucide";
import { Button, ButtonGroup, Icon } from "areia";

export default ilha.render(() => (
  <ButtonGroup aria-label="Text formatting">
    <Button
      variant="outline"
      shape="square"
      icon={<Icon icon={Bold} />}
      aria-label="Bold"
    />
    <Button
      variant="outline"
      shape="square"
      icon={<Icon icon={Italic} />}
      aria-label="Italic"
    />
    <Button
      variant="outline"
      shape="square"
      icon={<Icon icon={Underline} />}
      aria-label="Underline"
    />
  </ButtonGroup>
));

Use orientation="vertical" for stacked groups, ButtonGroup.Text for text segments, and ButtonGroup.Separator to separate controls.

Page 1

import { ilha } from "ilha";
import { Button, ButtonGroup } from "areia";

export default ilha.render(() => (
  <ButtonGroup>
    <Button variant="outline">Back</Button>
    <ButtonGroup.Separator />
    <ButtonGroup.Text>Page 1</ButtonGroup.Text>
    <ButtonGroup.Separator />
    <Button variant="outline">Next</Button>
  </ButtonGroup>
));

Link as Button

Use LinkButton when the interaction should navigate somewhere but still look like a button. Use Button for in-place actions like submitting, opening, or toggling UI.

Read Link docs Ilha Docs

import { ilha } from "ilha";
import { ExternalLink } from "lucide";
import { LinkButton, Icon } from "areia";

export default ilha.render(() => (
  <div class="flex flex-wrap items-center gap-3">
    <LinkButton href="/components/link" variant="secondary">
      Read Link docs
    </LinkButton>
    <LinkButton
      href="https://ilha.build/"
      variant="ghost"
      icon={<Icon icon={ExternalLink} />}
      external
    >
      Ilha Docs
    </LinkButton>
  </div>
));

API Reference

Prop	Type	Default	Description
`shape`	`"base" \| "square" \| "circle"`	`"base"`	Controls the button shape.
`size`	`"xs" \| "sm" \| "base" \| "lg"`	`"base"`	Controls button height, padding, gap, and text size.
`variant`	`"primary" \| "secondary" \| "ghost" \| "destructive" \| "secondary-destructive" \| "outline"`	`"secondary"`	Controls the visual style.
`children`	`unknown`	-	Content rendered inside the button.
`class`	`string`	-	Additional CSS classes merged with the generated classes.
`className`	`string`	-	Alias for `class`.
`icon`	`unknown`	-	Markup rendered before the label.
`loading`	`boolean`	-	Shows a loading spinner and disables interaction.
`title`	`string`	-	Native tooltip text.
`disabled`	`boolean`	-	Disables the button.
`name`	`string`	-	Native button name attribute.
`type`	`"submit" \| "reset" \| "button"`	`"button"`	Native button type attribute.
`value`	`string \| string[] \| number`	-	Native button value attribute.

ButtonGroup

Prop	Type	Default	Description
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout direction for grouped items.
`children`	`unknown`	-	Grouped controls.
`class`	`string`	-	Additional CSS classes.
`className`	`string`	-	Alias for `class`.

ButtonGroup.Text

Text segment for use inside ButtonGroup. Accepts standard div attributes plus children, class, and className.

ButtonGroup.Separator

Separator segment for use inside ButtonGroup.

Prop	Type	Default	Description
`orientation`	`"horizontal" \| "vertical"`	`"vertical"`	Separator orientation.
`class`	`string`	-	Additional CSS classes.
`className`	`string`	-	Alias for `class`.