# Examples

Examples of registry items: styles, components, css vars, etc.

Source: https://webjs.dev/ui/docs/registry/examples

## registry:style

**Note:** The look of the WebJs UI components is chosen by the `style` field of `components.json`, which the CLI bakes into every file it writes. A `registry:style` item does not change that. It installs like any other item: its files, its dependencies and its CSS variables.

### Custom style that builds on the kit

The following registry item bundles a starting point for Acme apps. On `add`, it will:

- Install `date-fns` as a dependency.
- Add the `login-01` and `calendar` items from the same registry.
- Set the `font-sans` variable to `Inter, sans-serif`, if the stylesheet does not set it.
- Install a `brand` color in light and dark mode.

```json title="example-style.json"
{
  "name": "example-style",
  "type": "registry:style",
  "dependencies": ["date-fns"],
  "registryDependencies": ["login-01", "calendar"],
  "cssVars": {
    "theme": {
      "font-sans": "Inter, sans-serif",
      "color-brand": "var(--brand)"
    },
    "light": {
      "brand": "oklch(0.205 0.015 18)"
    },
    "dark": {
      "brand": "oklch(0.985 0 0)"
    }
  }
}
```

### Custom style from scratch

A style from scratch is a style item whose `registryDependencies` are all your own items, and whose CSS variables are new names. The CLI installs exactly what an item lists.

```json title="example-style.json"
{
  "name": "new-style",
  "type": "registry:style",
  "registryDependencies": ["button", "input", "label", "select"],
  "cssVars": {
    "theme": {
      "color-main": "var(--main)",
      "color-bg": "var(--bg)"
    },
    "light": {
      "main": "#88aaee",
      "bg": "#dfe5f2"
    },
    "dark": {
      "main": "#88aaee",
      "bg": "#272933"
    }
  }
}
```

Here `button`, `input`, `label` and `select` are fetched from your registry. Each lands in the user's `components/ui` folder, and `add` asks before replacing a file of the same name that is already there.

## registry:theme

### Custom theme

A theme item's `cssVars` add the variables a project does not define. A project that ran `webjs ui init` already defines `--background`, `--primary` and the rest, so to change those values, ship the theme as a CSS file and tell users to import it after their theme.

```json title="example-theme.json"
{
  "name": "custom-theme",
  "type": "registry:theme",
  "files": [
    {
      "path": "themes/blue.css",
      "type": "registry:file",
      "target": "styles/theme-blue.css"
    }
  ]
}
```

```css title="themes/blue.css"
:root {
  --primary: oklch(0.546 0.245 262.881);
  --primary-foreground: oklch(0.97 0.014 254.604);
  --ring: oklch(0.746 0.16 232.661);
}

.dark {
  --primary: oklch(0.707 0.165 254.624);
  --primary-foreground: oklch(0.97 0.014 254.604);
  --ring: oklch(0.707 0.165 254.624);
}
```

### Custom colors

The following item adds a custom `brand` color to a project that has the default theme.

```json title="example-colors.json"
{
  "name": "custom-colors",
  "type": "registry:theme",
  "cssVars": {
    "theme": {
      "color-brand": "var(--brand)"
    },
    "light": {
      "brand": "oklch(0.99 0.00 0)"
    },
    "dark": {
      "brand": "oklch(0.14 0.00 286)"
    }
  }
}
```

## registry:block

### Custom block

This block installs a login page and the form component it renders.

```json title="login-01.json"
{
  "name": "login-01",
  "type": "registry:block",
  "description": "A simple login form.",
  "categories": ["authentication", "login"],
  "registryDependencies": ["button", "card", "input", "label"],
  "files": [
    {
      "path": "blocks/login-01/page.ts",
      "content": "import { html } from '@webjsdev/core'; ...",
      "type": "registry:page",
      "target": "app/login/page.ts"
    },
    {
      "path": "blocks/login-01/components/login-form.ts",
      "content": "...",
      "type": "registry:block",
      "target": "components/login-form.ts"
    }
  ]
}
```

Every file of a block names its `target`, so the page lands at its route. An existing block file is kept unless `add` is run with `--overwrite`, since it is app code the user owns.

### Install a block with your own primitives

A block's registry dependencies come from the block's own registry. So a block that depends on `button`, `input` and `label` installs your versions of them, not the WebJs UI ones, and the user is asked before an existing file is replaced.

```json title="custom-login.json"
{
  "name": "custom-login",
  "type": "registry:block",
  "registryDependencies": ["login-01", "button", "input", "label"]
}
```

## registry:ui

### UI component

A `registry:ui` item is a reusable UI component. It can have dependencies, registry dependencies, and CSS variables. A Tier-1 component is a set of class helpers, a Tier-2 component a custom element built on `@webjsdev/core`.

```json title="button.json"
{
  "name": "button",
  "type": "registry:ui",
  "files": [
    {
      "path": "components/button.ts",
      "content": "...",
      "type": "registry:ui"
    }
  ]
}
```

### UI component with CSS variables

```json title="sidebar.json"
{
  "name": "sidebar",
  "type": "registry:ui",
  "registryDependencies": ["button", "separator", "sheet", "tooltip"],
  "files": [
    {
      "path": "components/sidebar.ts",
      "content": "...",
      "type": "registry:ui"
    }
  ],
  "cssVars": {
    "light": {
      "sidebar": "oklch(0.985 0 0)",
      "sidebar-foreground": "oklch(0.141 0.005 285.823)",
      "sidebar-border": "oklch(0.92 0.004 286.32)"
    },
    "dark": {
      "sidebar": "oklch(0.141 0.005 285.823)",
      "sidebar-foreground": "oklch(0.985 0 0)",
      "sidebar-border": "oklch(0.274 0.006 286.033)"
    }
  }
}
```

On `add`, each variable the user's stylesheet lacks is added to its `:root` or `.dark` block, so the component renders in an app whose theme predates it.

## registry:lib

### Utility library

A `registry:lib` item is a utility library. Use it to share helper functions, constants, or other non-component code. Its files land in the `lib` folder `components.json` names.

```json title="format.json"
{
  "name": "format",
  "type": "registry:lib",
  "dependencies": ["date-fns"],
  "files": [
    {
      "path": "lib/format.ts",
      "content": "export { format } from 'date-fns';",
      "type": "registry:lib"
    }
  ]
}
```

## registry:hook

### Custom controller

A `registry:hook` file lands in `hooks/`, which suits reusable component logic such as a reactive controller.

```json title="media-query.json"
{
  "name": "media-query",
  "type": "registry:hook",
  "files": [
    {
      "path": "hooks/media-query.ts",
      "content": "...",
      "type": "registry:hook"
    }
  ]
}
```

## Targets

A `target` is a path from the project root, written as is, and it decides where the file lands even when it differs from the file `type`.

```json title="type-mismatch.json"
{
  "name": "type-mismatch",
  "type": "registry:item",
  "files": [
    {
      "path": "lib/format-date.ts",
      "type": "registry:ui",
      "target": "lib/format-date.ts",
      "content": "..."
    }
  ]
}
```

To land a file in the user's configured folder instead, leave out `target` and let the file `type` pick it: `registry:ui` for `aliases.ui`, `registry:component` for `aliases.components`, `registry:lib` for `aliases.lib`.

## registry:font

Ship the font family as a theme variable, and the font files, if any, as `registry:file` entries.

```json title="font-inter.json"
{
  "name": "font-inter",
  "type": "registry:font",
  "cssVars": {
    "theme": {
      "font-sans": "'Inter Variable', sans-serif"
    }
  }
}
```

## registry:base

A `registry:base` item gets no special handling either. A whole design system ships as a style item whose `registryDependencies` list its components, as in Custom style from scratch.

## Common Fields

### Author

Use the `author` field to add attribution to your registry items. It is kept in the item, and the CLI does not print it.

```json title="example-item.json"
{
  "name": "custom-component",
  "type": "registry:ui",
  "author": "Acme",
  "files": [
    {
      "path": "components/custom-component.ts",
      "content": "...",
      "type": "registry:ui"
    }
  ]
}
```

### Dev dependencies

Use the `devDependencies` field to install packages as dev dependencies.

```json title="example-item.json"
{
  "name": "custom-item",
  "type": "registry:item",
  "devDependencies": ["@types/node"],
  "files": [
    {
      "path": "lib/paths.ts",
      "content": "...",
      "type": "registry:lib"
    }
  ]
}
```

### Metadata

Use the `meta` field to attach arbitrary metadata to your registry items. This can be used to store custom data that your tools or scripts can use.

```json title="example-item.json"
{
  "name": "custom-component",
  "type": "registry:ui",
  "meta": {
    "category": "forms",
    "version": "2.0.0"
  },
  "files": [
    {
      "path": "components/custom-component.ts",
      "content": "...",
      "type": "registry:ui"
    }
  ]
}
```

## CSS Variables

### Custom Theme Variables

Add custom theme variables to the `theme` object. They land in the stylesheet's `@theme inline` block.

```json title="example-theme.json"
{
  "name": "custom-theme",
  "type": "registry:theme",
  "cssVars": {
    "theme": {
      "font-heading": "Inter, sans-serif",
      "shadow-card": "0 0 0 1px rgba(0, 0, 0, 0.1)"
    }
  }
}
```

### Override Tailwind CSS variables

A `theme` entry for one of Tailwind's own variables overrides Tailwind's default, because the default lives in Tailwind and not in the project's stylesheet. A variable the stylesheet already defines is left alone.

```json title="example-theme.json"
{
  "name": "custom-theme",
  "type": "registry:theme",
  "cssVars": {
    "theme": {
      "spacing": "0.2rem",
      "breakpoint-sm": "640px",
      "breakpoint-md": "768px",
      "breakpoint-lg": "1024px",
      "breakpoint-xl": "1280px",
      "breakpoint-2xl": "1536px"
    }
  }
}
```

## Add custom CSS

Base styles, component styles, `@utility` rules, `@import`, `@plugin` and `@keyframes` all ship the same way: as a CSS file the user imports.

```json title="acme-css.json"
{
  "name": "acme-css",
  "type": "registry:style",
  "files": [
    {
      "path": "styles/acme.css",
      "type": "registry:file",
      "target": "styles/acme.css"
    }
  ]
}
```

```css title="styles/acme.css"
@layer base {
  h1 {
    font-size: var(--text-2xl);
  }
}

@utility content-auto {
  content-visibility: auto;
}

@keyframes wiggle {
  0%, 100% { transform: rotate(-3deg); }
  50% { transform: rotate(3deg); }
}
```

Users then import it after Tailwind in their stylesheet:

```css
@import "tailwindcss";
@import "./acme.css";
```

## Add environment variables

Ship example variables as a file.

```json title="example-item.json"
{
  "name": "custom-item",
  "type": "registry:item",
  "files": [
    {
      "path": "env/.env.example",
      "type": "registry:file",
      "target": ".env.example"
    }
  ]
}
```

**IMPORTANT:** Ship development or example variables only. Do NOT put production values or secrets in a registry item.

## Universal Items

An item whose files all name a `target` installs the same way in any project, whatever its `components.json` aliases say. The project still needs a `components.json`, since `add` stops without one.

Here's an example of a registry item that installs agent rules:

```json title="acme-rules.json"
{
  "name": "acme-rules",
  "type": "registry:item",
  "files": [
    {
      "path": "rules/acme.md",
      "type": "registry:file",
      "target": ".agents/rules/acme.md",
      "content": "..."
    }
  ]
}
```

You can also have a universal item that installs multiple files:

```json title="my-custom-starter-template.json"
{
  "name": "my-custom-starter-template",
  "type": "registry:item",
  "dependencies": ["zod"],
  "files": [
    {
      "path": "starter/app/page.ts",
      "type": "registry:file",
      "target": "app/page.ts",
      "content": "..."
    },
    {
      "path": "starter/modules/home/queries/get-home.server.ts",
      "type": "registry:file",
      "target": "modules/home/queries/get-home.server.ts",
      "content": "..."
    }
  ]
}
```
