---
title: Getting Started
description: "Install Areia and start building Ilha interfaces with imports first, customization later."
order: 0
tags: [components]
---

import { Preview } from "$lib/components/preview";
import { Button } from "areia";

# Getting Started

Areia is a Vanilla TypeScript-first UI kit for Ilha. Start by importing ready-made components, then eject/copy component source later when your product needs deeper customization.

## Install

Install Areia in your Ilha project:

```bash
npm install areia
# or: bun add areia
# or: pnpm add areia
```

Some components use optional peer packages. For example, install `sonner` when using the Sonner/Toaster component:

```bash
npm install sonner
# or: bun add sonner
# or: pnpm add sonner
```

## Import a component

Use components directly from `areia`:

<Preview
  code={
    'import ilha from "ilha";\nimport { Button } from "areia";\n\nexport default ilha.render(() => (\n  <Button variant="primary">Create project</Button>\n));'
  }
  lang="tsx"
>
  <Button variant="primary">Create project</Button>
</Preview>

## Use JSX or html literals

Areia components are designed for Ilha and can be used with JSX or Ilha's html literal style.

<Preview
  code={
    'import ilha, { html } from "ilha";\nimport { Button } from "areia";\n\n// Default JSX syntax\nexport default ilha.render(() => (\n  <div class="flex gap-2">\n    <Button variant="primary">Save</Button>\n    <Button variant="secondary">Cancel</Button>\n  </div>\n));\n\n// No-build html template literal\nexport default ilha.render(\n  () => html`\n    <div class="flex gap-2">\n      ${Button({ variant: "primary", children: "Save" })}\n      ${Button({ variant: "secondary", children: "Cancel" })}\n    </div>\n  `,\n);'
  }
  lang="tsx"
>
  <div class="flex gap-2">
    <Button variant="primary">Save</Button>
    <Button variant="secondary">Cancel</Button>
  </div>
</Preview>

## Add styles

Areia is handcrafted with Tailwind. First, install and configure Tailwind in your app — the [Tailwind Vite installation guide](https://tailwindcss.com/docs/installation/using-vite) is the recommended starting point for Vite-based Ilha projects.

After Tailwind is configured, make sure your app styles are loaded by Ilha. A minimal app stylesheet might look like this:

```css
@import "tailwindcss";
@plugin "areia";
```

`@plugin "areia"` registers the full `--areia-*` token set (light and dark), maps them into Tailwind utilities, adds a `dark:` variant for `.dark` roots, and scans Areia's built output in `node_modules` for class names.

Then add your own utilities and overrides as your app grows.

## Theme Areia

Areia components rely on Tailwind utilities backed by `--areia-*` design tokens. Load the built-in theme with:

```css
@import "tailwindcss";
@plugin "areia";
```

Or import the bundled entry:

```css
@import "tailwindcss";
@import "areia/tailwind.css";
```

Override any token in `:root` or `.dark` after loading the theme.

Most components use the same token groups: surfaces (`background`, `surface`, `surface-muted`), text (`foreground`, `text-default`, `text-subtle`), borders/focus (`border`, `divider`, `ring`), controls (`control-background`, `control-hover`, `control-active`), and semantic colors (`primary`, `success`, `warning`, `destructive`, `info`). Copy the full token set from `docs.css` when you want complete coverage for every component variant.

## Customize later

The recommended flow is progressive:

1. Import components from `areia` to move quickly.
2. Build screens and product flows with the default behavior.
3. When a component needs custom behavior or markup, copy/eject its source into your app.
4. Keep using Areia primitives and Tailwind conventions around your customized components.

This keeps the early development loop fast while still giving you ownership of the final UI.