# Blocks

Install a ready-made view, then make it yours. Or contribute one to the blocks library.

Source: https://webjs.dev/ui/docs/blocks

A block is a ready-made view you install and then edit: a login or signup page, an app sidebar shell, a dashboard, a chart. Its files land in your app as code you own, so you spend your time on the app instead of rebuilding a page shell. Browse them on the [blocks page](https://webjs.dev/ui/blocks).

On the wire a block is a `registry:block` item. A chart is a block whose categories include `chart`.

## Find a block

List the blocks with their one-line descriptions:

```bash
npx @webjsdev/ui list --type block
```

Narrow the list to one category, or print it as JSON for a script or an agent:

```bash
npx @webjsdev/ui list --category login --json
```

The JSON form is one compact array of `{ name, type, categories, description }`. `--type chart` lists the charts the same way. An agent with the WebJs MCP server can ask the `ui` tool instead: with no arguments it returns the block and chart names grouped by category, and `{ type: "block" }` or `{ category: "login" }` adds the descriptions. See [Skills](https://webjs.dev/ui/docs/skills).

## Preview a block

Before installing, see what a block writes and where:

```bash
npx @webjsdev/ui view login-03 --files-only
```

```txt
# login-03  (block)

A login page with a muted background color.

categories: authentication, login
registry deps: lib-utils, button, card, field, input
npm: @webjsdev/core

Install: npx @webjsdev/ui add login-03

Files:
  app/login/page.ts
  components/login-form.ts
```

Without `--files-only`, `view` prints the sources after the file list, baked with your project's style. `--json` prints the same projection as one document.

## Install a block

### Run the add command

```bash
npx @webjsdev/ui add login-03
```

The command installs the components the block uses, writes each of the block's files to its target and prints the list of files it wrote.

### Open the page

The page lands at its route under `app/`, so `login-03` is served at `/login` as soon as `npm run dev` picks it up.

A block page renders inside your root layout, like every page. The root layout `webjs create` writes puts every page in a centered `max-w-5xl` column under a navbar, and a full-screen block (the login, signup, sidebar and dashboard blocks) needs the whole viewport. Let the root layout render `${children}` bare, and move the column into a route group's layout, such as `app/(site)/layout.ts`, for the pages that want it.

### Wire the form

A block ships no server action, so its `<form>` has no `action` yet. Bind your own `'use server'` action to it:

```ts title="components/login-form.ts"
import { signIn } from '#modules/auth/actions/sign-in.server.ts';

export function loginForm(opts: { class?: string } = {}) {
  return html`
    <form action=${signIn} class=${cn('flex flex-col gap-6', opts.class)}>
      ...
    </form>
  `;
}
```

The framework then supplies `method="post"`, and the form submits with JavaScript off, re-renders with `fieldErrors` and `values` on a failure, and follows the redirect on success. See [Forms](https://webjs.dev/ui/docs/forms).

### Make it yours

Rename the route, change the copy, swap the logo and the cover image. The files are yours, and nothing upstream changes them again.

## What add does

A block installs through the same `add` command as a component, with a few differences that follow from its files being app code.

- **Every file has a target.** Each one lands at its own path under the app (`app/...`, `components/...`, `modules/...`, `public/...`) rather than in your `components/ui` folder.
- **Imports are rewritten.** A block's files import with registry-relative paths. `add` rewrites every one to where the imported file landed: a kit component to your `ui` alias, the `cn()` helper to your `utils` alias, another file of the same block to its own target.
- **Existing files are kept.** A file that already exists is never replaced without `--overwrite`, not even under `--yes`. Blocks of one family share targets (every login block writes `app/login/page.ts`), so installing a second one keeps the first one's files unless you ask. Families can overlap too: every sidebar block and `dashboard-01` write `app/dashboard/page.ts`, `components/app-sidebar.ts`, `components/nav-main.ts` and `components/nav-user.ts`, so adding `dashboard-01` after `sidebar-07` keeps the sidebar block's page and parts and leaves the dashboard's other files unused. Install one app shell per app, or pass `--overwrite` to switch.
- **Missing tokens are added.** A block that needs design tokens your theme may lack carries them, and `add` adds only the ones your stylesheet's `:root`, `.dark` or `@theme inline` block does not define. A token you already set is left alone.
- **Nothing is stripped.** A block's files are written whole, with no example removed.

`diff` includes installed blocks, so `npx @webjsdev/ui diff login-03` shows how your copy has moved from the registry's.

## Charts

A chart installs the same way and writes one file, `components/charts/<name>.ts`, plus the `chart` and `card` components it uses. Its default export renders the chart's card, so render it from any page:

```bash
npx @webjsdev/ui add chart-bar-interactive
```

```ts title="app/stats/page.ts"
import { html } from '@webjsdev/core';
import ChartBarInteractive from '#components/charts/chart-bar-interactive.ts';

export default function Page() {
  return html`<main class="p-8">${ChartBarInteractive()}</main>`;
}
```

Browse every chart in the [Charts Library](https://webjs.dev/ui/charts/area).

## Add a block to the kit

We'd love to see all types of blocks: applications, marketing, products, and more. A block is contributed to the kit's registry in the WebJs repository.

### Fork the repository

```bash
git clone https://github.com/webjsdev/webjs.git
```

### Create a new branch

```bash
git checkout -b username/my-new-block
```

### Create the block folder

Create a folder named in kebab-case under `packages/ui/packages/registry/blocks`, and add the block's files to it. A block can be one file or a page with its own parts.

```txt
packages
└── ui
    └── packages
        └── registry
            └── blocks
                └── login-01
                    ├── page.ts
                    └── components
                        └── login-form.ts
```

### Add the block to registry.json

Add an item to `packages/ui/packages/registry/registry.json`. It follows the same item schema as a component, with a `target` on every file.

```json title="packages/ui/packages/registry/registry.json"
{
  "name": "login-01",
  "type": "registry:block",
  "title": "Login 01",
  "description": "A simple login form.",
  "categories": ["authentication", "login"],
  "registryDependencies": ["lib-utils", "button", "card", "field", "input"],
  "dependencies": ["@webjsdev/core"],
  "files": [
    {
      "path": "blocks/login-01/page.ts",
      "type": "registry:page",
      "target": "app/login/page.ts"
    },
    {
      "path": "blocks/login-01/components/login-form.ts",
      "type": "registry:component",
      "target": "components/login-form.ts"
    }
  ]
}
```

### Run the tests

```bash
npm test --workspace=@webjsdev/ui
```

The block tests check that every file has a target under the app, exists and is not empty, that every relative import resolves to a file the install also writes, and they install the block into a scratch app and render its page on the server.

### Submit a pull request

Commit your changes and open a pull request. Once it is merged and released, the block is listed by `list` and installs with `add`.

## Categories

The `categories` property organizes blocks in the registry, broad to specific: `["authentication", "login"]`, `["chart", "area"]`. `list --category` and the MCP `ui` tool group and filter by them, and a block whose categories include `chart` is listed as a chart.

## Guidelines

Here are some guidelines to follow when contributing to the blocks library.

- The following properties are required for the block definition: `name`, `description`, `type`, `files`, and `categories`.
- Every file needs a `target` under the app. A page goes under `app/` so the file router serves it.
- List every component the block imports in `registryDependencies`, plus `lib-utils` when it uses `cn()`.
- **Imports are registry-relative**, for example `'../../../components/card.ts'` or `'./components/login-form.ts'`. `add` rewrites them to the app's aliases.
- A page is a server-rendered page module: a default-exported function, plus a `metadata` export.
- A part that is not interactive is a fragment helper, a function returning an `html` template, not a custom element. Two blocks can share a part's name, and a tag can be defined only once per page session.
- A form is a real `<form>` with named controls and no `action`. Its header comment says to bind one.
- Draw icons and brand marks as inline SVG.
- Compose the kit's helpers rather than writing their classes by hand, so the block takes the app's style when it is installed.

Note

Do not reach for a third-party runtime dependency in a block. The kit takes none, and a block is held to the same rule.
