# User blueprint

User blueprints are located in `/site/blueprints/users` and control the Panel setup, form fields and permissions for a user role.

****

- Read more: <https://getkirby.com/docs/guide/blueprints/introduction>

****

## Blueprint location

```filesystem
/site/blueprints/users/
```

## Default user blueprint

To create the same set of fields for all roles, you can setup a `default.yml` that is used whenever no custom role blueprint is configured.

```filesystem
/site/blueprints/users/default.yml
```

## Title and description

The title is required and will appear in the list of selectable roles when a new user is created. An optional description can be displayed as well:

```yaml
title: Client
description: The client can edit all pages
```

### Translated titles

Title and description can be translated by passing an array of translations with the matching language code as key:

```yaml
title:
  en: Client
  de: Kunde
description:
  en: The client can edit all pages
  de: Der Kunde kann alle Seiten bearbeiten
```

## Home option

When a user logs in to the Panel, they normally get redirected to the last view they were on before they were logged out or the Site view. When you work with permissions, you might want to block the Site view or redirect the user to a completely different view instead. This is now possible with the new `home` option for user blueprints. This way you can define the redirect for each role individually. Redirects can be simple paths or dynamic locations via string queries.

### Simple paths

```yaml "/site/blueprints/users/editor.yml"
title: Editor
home: /panel/account
```

### Queries to panel views

```yaml "/site/blueprints/users/editor.yml"
title: Editor
home: "{{ site.find('blog').children.first.panel.url }}"
```

### Queries to pages

```yaml "/site/blueprints/users/editor.yml"
title: Editor
home: "{{ site.find('blog').children.first.url }}"
```

## Image options

The image options for users can now be defined directly in their own blueprint. This significantly simplifies the setup of sections as they all inherit the image settings. You can still set image settings in sections the good old way if needed.

```yaml "site/blueprints/user/editor.yml"
image:
  back: blue-200
  icon: 📝
```

### Support for queries

Panel preview image options now all support our powerful queries:

```yaml "site/blueprints/users/editor.yml"
image:
  back: "{{ user.myCustomBackColor }}"
```

### Custom colors
`back` and `color` options for Panel preview images now support shorthands for core CSS color variables as well as HEX codes or other native CSS color properties (e.g. even gradients):

#### CSS color property shorthands

```yaml
image:
  back: "purple-400"
```
Check out the <a href="https://lab.getkirby.com/public/lab/basics/design/colors">list of our color properties</a> for available options.

#### Hex codes

```yaml
image:
  back: "#ff0000"
```

#### CSS rules

```yaml
image:
  back: "linear-gradient(90deg, rgba(2,0,36,1) 0%, rgba(9,9,121,1) 35%, rgba(0,212,255,1) 100%);"
```

## Options

With options, you can control which actions are available for users with this role. Options can be set for all users or individually per user role.

Role-specific options take precedence over the corresponding <a href="#permissions">permissions</a>. If no option matches, Kirby falls back to the permissions of the current user.

| Option | Value |
|----    | ---- |
| `access` | `true`/`false` |
| `changeEmail` | `true`/`false` |
| `changeLanguage` | `true`/`false` |
| `changeName` | `true`/`false` |
| `changePassword` | `true`/`false` |
| `changeRole` | `true`/`false` |
| `create` | `true`/`false` |
| `delete` | `true`/`false` |
| `list` | `true`/`false` |
| `update` | `true`/`false` |

<p>Each option can be set on a per user role for fine-grained permissions, for example:</p>
<figure class="code">
<pre><code class="language-yaml">options:
  delete:
    admin: true
    editor: false</code></pre>
</figure>
<p>Or using a wildcard to change the default for all roles:</p>
<figure class="code">
<pre><code class="language-yaml">options:
  update:
    *: false
    editor: true</code></pre>
</figure>
<p>Controlling accessibility for roles.</p>
<figure class="code">
<pre><code class="language-yaml"># Page is not accessible and not visible for all roles except admins.
options:
  access:
    *: false
    admin: true
  list:
    *: false
    admin: true</code></pre>
</figure>

### Creating users with a role

To only allow managers to create users with the `assistant` role:

```yaml "/site/blueprints/users/assistant.yml"
title: Assistant

options:
  create:
    "*": false
    manager: true
```

### Changing roles

When changing a user's role, Kirby checks:

1. The current role's `options.changeRole`
2. The new role's `options.create`

To allow managers to change assistants to editors:

```yaml "/site/blueprints/users/assistant.yml"
title: Assistant

options:
  changeRole:
    "*": false
    manager: true
```

```yaml "/site/blueprints/users/editor.yml"
title: Editor

options:
  create:
    "*": false
    manager: true
```

## Permissions

The `permissions` option can be used to restrict access to certain actions for the particular role. By default, all actions are allowed and you can deny them by passing `false`.

### `access`

| Option | Value |
|----    | ---- |
| `account` | `true`/`false` |
| `languages` | `true`/`false` |
| `panel` | `true`/`false` |
| `site` | `true`/`false` |
| `system`| `true`/`false` |
| `users` | `true`/`false`|

#### Example: Prevent accessing user management and system settings

```yaml
permissions:
  access:
    system: false
    users: false
```

<info>
`access.settings` was renamed to `access.system` in Kirby 3.6. The old key no longer has any effect.
</info>

#### Custom Panel areas

Plugins that register a Panel area automatically add an `access.<areaId>` key, so custom areas can be restricted the same way as core ones:

```yaml
permissions:
  access:
    todos: false
```

### `files`

| Option | Value |
|----    | ---- |
| `access` | `true`/`false` |
| `changeName` | `true`/`false` |
| `changeTemplate` | `true`/`false` |
| `create` | `true`/`false` |
| `delete` | `true`/`false` |
| `list` | `true`/`false` |
| `read` | `true`/`false` |
| `replace` | `true`/`false` |
| `sort` | `true`/`false` |
| `update` | `true`/`false` |

#### Example: Prevent deleting files

```yaml
permissions:
  files:
    delete: false
```

### `languages`

| Option | Value |
|----    | ---- |
| `create` | `true`/`false` |
| `delete` | `true`/`false` |
| `update` | `true`/`false` |

#### Example: Prevent creating and deleting languages

```yaml
permissions:
  languages:
    create: false
    delete: false
```

### `pages`

| Option | Value |
|----    | ---- |
| `access` | `true`/`false` |
| `changeSlug` | `true`/`false` |
| `changeStatus` | `true`/`false` |
| `changeTemplate` | `true`/`false` |
| `changeTitle` | `true`/`false` |
| `create` | `true`/`false` |
| `delete` | `true`/`false` |
| `duplicate` | `true`/`false` |
| `list` | `true`/`false` |
| `move` | `true`/`false` |
| `preview` | `true`/`false` |
| `read` | `true`/`false` |
| `sort` | `true`/`false` |
| `update` | `true`/`false` |

#### Example: Prevent deleting and creating pages and changing their template

```yaml
permissions:
  pages:
    delete: false
    create: false
    changeTemplate: false
```

### `site`

| Option | Value |
|----    | ---- |
| `access` | `true`/`false` |
| `changeTitle` | `true`/`false` |
| `preview` | `true`/`false` |
| `update` | `true`/`false` |

### `users`

The `users` setting can be set generally to `false` to prevent the user from editing, adding or deleting other users.

```yaml
users: false
```

It is also possible to set the `users` options individually.

| Option | Value |
|----    | ---- |
| `access` | `true`/`false` |
| `changeEmail` | `true`/`false` |
| `changeLanguage` | `true`/`false` |
| `changeName` | `true`/`false` |
| `changePassword` | `true`/`false` |
| `changeRole` | `true`/`false` |
| `create` | `true`/`false` |
| `delete` | `true`/`false` |
| `list` | `true`/`false` |
| `update` | `true`/`false` |

#### Example:

```yaml
permissions:
  access:
    users: true
  users:
    delete: false
    create: false
    changeRole: false
```

### `user`

This option refers to each user with this role.

| Option | Value |
|----    | ---- |
| `access` | `true`/`false` |
| `changeEmail` | `true`/`false` |
| `changeLanguage` | `true`/`false` |
| `changeName` | `true`/`false` |
| `changePassword` | `true`/`false` |
| `changeRole` | `true`/`false` |
| `delete` | `true`/`false` |
| `list` | `true`/`false` |
| `update` | `true`/`false` |

#### Example

This user can access the user management, but not edit other users. The user cannot change their own role or delete themselves.

```yaml
permissions:
  access:
    users: true
  users: false
  user:
    delete: false
    changeRole: false
```

### Using wildcards

It's also possible to restrict access to entire blocks by just passing `false` to the block:

```yaml
permissions:
  pages: false
```

<details class="since list-none" open="1">
<summary >
	Since <a href="https://github.com/getkirby/kirby/releases/tag/5.0.0">5.0.0</a></summary>
<div>
	<h2 id="view-buttons"><a href="#view-buttons" tabindex="-1">View buttons</a></h2>
<p>Kirby allows you to define what buttons to use for this user. To select which (default) buttons to show on a particular view you can set the <code class="type">buttons</code> option in the corresponding blueprint:</p>
<figure class="code">
<pre><code class="language-yml">buttons:
  settings: true</code></pre>
</figure>
<p>By setting the value to <code class="type type-bool">true</code>, you can reference existing buttons (from the <a href="https://getkirby.com/docs/reference/system/options/panel/panel-view-buttons#referencing-buttons">core or <code class="type">config.php</code> file</a> or even <a href="https://getkirby.com/docs/reference/plugins/extensions/panel-view-buttons">Panel area plugin extensions</a>) by name and decide which ones to include and in what order.</p>
<h3 id="view-buttons__create-a-new-button"><a href="#view-buttons__create-a-new-button" tabindex="-1">Create a new button</a></h3>
<p>You can now also define your own custom buttons directly in a blueprint:</p>
<figure class="code">
<pre><code class="language-yml">buttons:
  settings: true
  social:
    icon: mastodon
    text: Mastodon
    link: "https://mastodon.social/@getkirby"
    theme: purple-icon</code></pre>
</figure>
<p>The available options are based on the <a href="https://lab.getkirby.com/public/lab/docs/k-view-button"><code class="type">k-view-button</code> component</a>. Check out the <a href="https://getkirby.com/docs/reference/system/options/panel/panel-view-buttons">config option documentation</a> for more details, e.g. in regard to available attributes or query support.</p>
<h3 id="view-buttons__disable-all-buttons"><a href="#view-buttons__disable-all-buttons" tabindex="-1">Disable all buttons</a></h3>
<figure class="code">
<pre><code class="language-yml">buttons: false</code></pre>
</figure></div>
</details>

## Examples

You can find examples of user blueprints in the <a href="https://getkirby.com/docs/reference/panel/samples/user">samples section</a>.