# Branding

Customize the admin panel logo, favicon, brand colors, and Visual Schema Builder visibility.

The `admin.branding` key in `nextly.config.ts` controls the visual identity of the admin panel. You can replace the default logo, set a custom favicon, override the primary and accent brand colors, and toggle the Visual Schema Builder's visibility.

## Full example

```typescript title="nextly.config.ts"
import { defineConfig } from "nextly";

export default defineConfig({
  admin: {
    branding: {
      logoUrl: "/logo.svg",
      logoUrlLight: "/logo-light.svg",
      logoUrlDark: "/logo-dark.svg",
      logoText: "Acme CMS",
      favicon: "/favicon.ico",
      colors: {
        primary: "#6366f1",
        accent: "#f59e0b",
      },
      showBuilder: true,
    },
  },
});
```

## Logo

You can ship a single logo for both light and dark modes, or a separate logo per mode.

| Option         | Type     | Description                                                                                                                                          |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `logoUrl`      | `string` | Logo image URL used in both modes. Absolute URL or path under your Next.js `public/` directory. When set, takes priority over the per-mode variants. |
| `logoUrlLight` | `string` | Logo for light mode. Used when `logoUrl` is not set.                                                                                                 |
| `logoUrlDark`  | `string` | Logo for dark mode. Used when `logoUrl` is not set.                                                                                                  |
| `logoText`     | `string` | Text shown in the sidebar header. Doubles as the `alt` attribute on the logo image. Default: `"Nextly"`.                                             |

If neither `logoUrl` nor the per-mode variants are set, the sidebar falls back to a default Nextly mark and shows `logoText` next to it.

```typescript title="nextly.config.ts"
// Single logo for both modes
admin: {
  branding: {
    logoUrl: "/logo.svg",
    logoText: "Acme CMS",
  },
},
```

```typescript title="nextly.config.ts"
// Separate logos per mode
admin: {
  branding: {
    logoUrlLight: "/logo-light.svg",
    logoUrlDark: "/logo-dark.svg",
    logoText: "Acme CMS",
  },
},
```

The mode-aware variants are wired up in `packages/admin/src/components/shared/ThemeAwareLogo.tsx`, which switches between `logoUrlLight` and `logoUrlDark` based on the resolved theme. `logoUrl` always wins when set.

## Favicon

`favicon` injects a custom favicon into every admin page (the `<link rel="icon">` element is replaced at runtime).

```typescript title="nextly.config.ts"
admin: {
  branding: {
    favicon: "/favicon.ico",
  },
},
```

The path can be absolute or a path under your Next.js `public/` folder. Common formats: `.ico`, `.png`, `.svg`. If `favicon` is unset, the admin uses a default inline SVG that follows the user's `prefers-color-scheme`. Browsers do not reliably react to JS-driven theme toggles for favicons, so the in-app dark/light switch will not change the favicon on the fly.

## Brand colors

```typescript title="nextly.config.ts"
admin: {
  branding: {
    colors: {
      primary: "#6366f1",  // indigo
      accent: "#f59e0b",   // amber
    },
  },
},
```

`branding.colors` accepts two 6-digit hex tokens that the admin actually consumes:

| Token     | Type       | Used for                                                                                                    |
| --------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| `primary` | hex string | Primary brand color (replaces the default blue): buttons, active states, links, focus rings, field accents. |
| `accent`  | hex string | Accent brand color (replaces the default cyan): secondary highlights.                                       |

Foreground colors for text and icons over each background are calculated automatically to meet WCAG AA contrast — you do not configure them. Both tokens are converted to HSL on the server and injected as CSS custom properties (`--primary`, `--primary-foreground`, `--accent`, `--accent-foreground`) so the change applies globally without runtime JS work. Invalid hex values are silently dropped; only `#rrggbb` is recognised.

If your `nextly.config.ts` is imported by your app's `layout.tsx`, you can render the generated CSS yourself with `getBrandingCss(config.admin?.branding)` from `nextly/config` to avoid a flash of default colors before the admin's runtime fetch.

## Schema Builder visibility

`showBuilder` toggles the Builders top-level icon (Collections Builder, Singles Builder, Field Groups Builder) in the admin sidebar.

| Value             | Behavior                                                                    |
| ----------------- | --------------------------------------------------------------------------- |
| `true`            | Builders icon is always visible.                                            |
| `false`           | Builders icon is always hidden.                                             |
| Not set (default) | Visible when `process.env.NODE_ENV !== "production"`, hidden in production. |

```typescript title="nextly.config.ts"
// Force visible, even in production
admin: {
  branding: {
    showBuilder: true,
  },
},
```

```typescript title="nextly.config.ts"
// Force hidden, even in development
admin: {
  branding: {
    showBuilder: false,
  },
},
```

The toggle is evaluated server-side and shipped via the `/admin/api/admin-meta` response, so changes take effect on the next admin reload. Hiding the Builder entry does not lock down the underlying routes — direct visits to `/admin/builder/collections` etc. still work for users with permission. Treat `showBuilder: false` as "hide from the sidebar in production", not as an authorization control.

## Branding options reference

| Option           | Type           | Default        | Description                                  |
| ---------------- | -------------- | -------------- | -------------------------------------------- |
| `logoUrl`        | `string`       | —              | Logo image URL (used in both modes when set) |
| `logoUrlLight`   | `string`       | —              | Logo for light mode                          |
| `logoUrlDark`    | `string`       | —              | Logo for dark mode                           |
| `logoText`       | `string`       | `"Nextly"`     | Sidebar header text and logo `alt` attribute |
| `favicon`        | `string`       | —              | Custom favicon URL                           |
| `colors.primary` | `string` (hex) | —              | Primary brand color                          |
| `colors.accent`  | `string` (hex) | —              | Accent brand color                           |
| `showBuilder`    | `boolean`      | per `NODE_ENV` | Toggle the Builders sidebar entry            |

## Next steps

* [Customization](https://nextlyhq.com/docs/admin/customization.md) — sidebar config, plugin overrides, navigation permissions
* [Admin Panel Overview](https://nextlyhq.com/docs/admin.md) — full navigation and feature guide
* [Visual Schema Builder](https://nextlyhq.com/docs/schema-builder.md) — what it does and how to use it