---
title: 'Grav 2.0 Developer Guide: Admin Next Custom Pages'
url: 'https://getgrav.org/blog/grav-2-dev-admin-next-custom-pages'
markdown: 'https://getgrav.org/blog/grav-2-dev-admin-next-custom-pages.md'
date: '2026-06-05'
description: "Yeti Search Pro isn't a settings page. Open it in Admin Next and you get a real search dashboard: index management, document counts, a live search tester, analytics, all in one place. SEO Magic is the same idea pointed at SEO: a crawl report, per-page scores, a re-crawl button, CSV export. These ar…"
taxonomy:
  category:
    - blog
  tag:
    - developer
    - grav2
    - plugins
    - admin-next
---

tutorial  10 mins 

#  Grav 2.0 Developer Guide: Admin Next Custom Pages 

Giving your plugin its own admin section, with a sidebar entry and a dedicated interface

 ![Andy Miller](https://getgrav.org/user/themes/event-horizon/images/authors/andy.png) Andy Miller · JUN 5, 2026 

 [developer](https://getgrav.org/blog?q=developer) [grav2](https://getgrav.org/blog?q=grav2) [plugins](https://getgrav.org/blog?q=plugins) [admin-next](https://getgrav.org/blog?q=admin-next) 

**Yeti Search Pro** isn't a settings page. Open it in **Admin Next** and you get a real search dashboard: index management, document counts, a live search tester, analytics, all in one place. **SEO Magic** is the same idea pointed at SEO: a crawl report, per-page scores, a re-crawl button, CSV export. These are mini-applications living inside the admin, not config forms with a fancy coat of paint.

That's what this post is about. The [custom fields post](https://getgrav.org/blog/grav-2-dev-admin-next-custom-fields) covered dropping a single web component into a form. This is the next step up: giving your plugin a top-level entry in the sidebar and a whole page of its own to do with as you like. It's the most involved Admin Next integration, and also the one that lets your plugin feel like a first-class part of the admin instead of a tab buried in Plugins.

There are two pieces to it: an item in the sidebar, and the page that item opens. Let's take them in that order.

## The Sidebar Entry

You add yourself to the sidebar by handling the `onApiSidebarItems` event. Admin Next asks the API for its sidebar list on load, the API fires this event, and every plugin that wants a spot appends one.

```php
public static function getSubscribedEvents(): array
{
    return [
        'onApiSidebarItems'   => ['onApiSidebarItems', 0],
        'onApiPluginPageInfo' => ['onApiPluginPageInfo', 0],
    ];
}

public function onApiSidebarItems(Event $event): void
{
    // Don't show the entry if the plugin is switched off
    if (!$this->config->get('plugins.my-plugin.enabled', true)) {
        return;
    }

    $items = $event['items'] ?? [];
    $items[] = [
        'id'        => 'my-plugin',
        'plugin'    => 'my-plugin',
        'label'     => 'My Plugin',
        'icon'      => 'fa-gauge',            // Font Awesome, full class with the fa- prefix
        'route'     => '/plugin/my-plugin',   // the Admin Next route this opens
        'priority'  => 5,                     // higher sorts earlier
        'authorize' => 'api.my-plugin.view',  // who's allowed to see it
    ];
    $event['items'] = $items;
}
```

A few things to know, because some of them used to work differently in classic admin:

- **The route is always `/plugin/{slug}`.** That's the Admin Next URL your page lives at. Stick to the convention.
- **Icons are Font Awesome with the `fa-` prefix.** Admin Next doesn't add the prefix for you, so it's `fa-gauge`, not `gauge`.
- **`authorize` controls visibility, and it's checked on the server.** Pass a permission string, or an array of strings for an any-of test. The API filters the list before it ever reaches the browser, and it strips `authorize` out of the response, so the client never even learns the entry existed. You can also pass a `badge` for a little count or status pill next to the label.
- **The sidebar is a flat list.** There's no nesting, no parent/child trees. Items are sorted by `priority` and that's it. If you have several related screens, you put one entry in the sidebar and switch between the screens inside your page (more on that below).

That's the whole sidebar story. Now the page it opens.

## The Page: Two Ways to Build It

When someone clicks your sidebar entry and lands on `/plugin/my-plugin`, Admin Next asks the API for the page definition (`GET /gpm/plugins/{slug}/page`). You provide that definition by handling `onApiPluginPageInfo`. The one decision that shapes everything else is the `page_type`, and there are exactly two: **blueprint** or **component**.

**Blueprint mode** hands Admin Next a Grav blueprint and lets it render the form. You write no JavaScript. This is the right call when your page is really a data screen: settings, a key-value editor, a structured config panel.

**Component mode** hands Admin Next a web component and gets out of your way. You get an empty container in the content area and you build whatever you want inside it: dashboards, tables, charts, a search tester. Yeti Search Pro and SEO Magic are both component-mode pages.

Pick one. A page is entirely one or entirely the other. There's no hybrid page where some parts are blueprint-rendered and some are custom, so don't go looking for one. I'll come back to how you get the best of both, because there's a clean answer that isn't a hybrid renderer.

### Blueprint Mode

```php
public function onApiPluginPageInfo(Event $event): void
{
    // Guard clause: only answer for your own plugin
    if ($event['plugin'] !== 'my-plugin') {
        return;
    }

    $event['definition'] = [
        'id'            => 'my-plugin',
        'plugin'        => 'my-plugin',
        'title'         => 'My Plugin',
        'icon'          => 'fa-gauge',
        'page_type'     => 'blueprint',
        'blueprint'     => 'my-plugin',         // the blueprint to render
        'data_endpoint' => '/my-plugin/data',   // GET: returns the current form values
        'save_endpoint' => '/my-plugin/save',   // PATCH: receives the edited values
        'actions'       => [
            ['id' => 'save', 'label' => 'Save', 'icon' => 'fa-check', 'primary' => true],
        ],
    ];
}
```

Admin Next fetches the blueprint, calls `data_endpoint` to fill it in, renders every field with the same native components the page editor uses, and saves back to `save_endpoint`. Your custom field types work here too, exactly as they did in the previous post. If the user has auto-save turned on, edits get debounced straight to the save endpoint with no Save click needed.

You don't get any of that for free in classic admin, and you write zero front-end code to get it here. The endpoints themselves are ordinary API routes from the [API integration post](https://getgrav.org/blog/grav-2-dev-api-integration).

### Component Mode

When a blueprint can't express what you need, switch to a component. The definition is shorter, because Admin Next isn't rendering anything for you:

```php
$event['definition'] = [
    'id'        => 'my-plugin',
    'plugin'    => 'my-plugin',
    'title'     => 'My Plugin',
    'icon'      => 'fa-gauge',
    'page_type' => 'component',
];
```

The component itself goes in `admin-next/pages/my-plugin.js`, one file named after your slug. Admin Next loads it on demand (`GET /gpm/plugins/{slug}/page-script`), hands it a tag name, and mounts it. It's the same web-component contract you already know from custom fields, minus the `field` and `value` properties, because a page isn't bound to a single form value. It fetches its own data and owns its own state.

```javascript
const TAG = window.__GRAV_PAGE_TAG;   // e.g. "grav-my-plugin--page"

function apiUrl(path) {
  return (window.__GRAV_API_SERVER_URL || '') +
         (window.__GRAV_API_PREFIX || '/api/v1') + path;
}

function apiHeaders() {
  const headers = {};
  if (window.__GRAV_API_TOKEN) headers['X-API-Token'] = window.__GRAV_API_TOKEN;
  return headers;
}

class MyPluginPage extends HTMLElement {
  connectedCallback() {
    this.attachShadow({ mode: 'open' });
    this._render();
    this._loadData();
  }

  async _loadData() {
    const resp = await fetch(apiUrl('/my-plugin/stats'), { headers: apiHeaders() });
    const json = await resp.json();
    this._stats = json.data || json;
    this._render();
  }

  _render() {
    this.shadowRoot.innerHTML = `
      <style>
        /* Read Admin Next's theme tokens so you match light/dark automatically */
        :host { display: block; color: var(--foreground); }
      </style>
      <div class="dashboard">...</div>
    `;
  }
}

customElements.define(TAG, MyPluginPage);
```

The same injected globals you get in a field component are here too: `window.__GRAV_API_SERVER_URL`, `__GRAV_API_PREFIX`, and `__GRAV_API_TOKEN` for talking to the API, plus `__GRAV_DIALOGS` for confirmations and `__GRAV_NAVIGATE` for moving around the admin. Send your token as `X-API-Token`, not `Authorization: Bearer`, for the same FastCGI reason covered in the last post.

## Header Actions

Both modes get a row of action buttons in the page header, declared in the `actions` array. This is where Save, Export, Re-crawl, and friends live. SEO Magic's real definition is a good tour of what's possible:

```php
'actions' => [
    [
        'id'       => 'recrawl',
        'label'    => 'Re-crawl',
        'icon'     => 'fa-refresh',
        'children' => [                              // a split button with a dropdown
            ['id' => 'recrawl-changed', 'label' => 'Re-crawl (changed only)', 'icon' => 'fa-refresh'],
        ],
    ],
    ['id' => 'export-csv', 'label' => 'Export CSV', 'icon' => 'fa-download'],   // triggers a download
    ['id' => 'options', 'label' => 'Options', 'icon' => 'fa-cog', 'navigate' => '/plugins/seo-magic'],
],
```

The keys you'll reach for most: `primary` highlights a button (your Save), `endpoint` plus `method` makes the button call an API route directly, `download` and `upload` turn it into a file download or upload, `confirm` puts a confirmation in front of it, `children` makes it a split button with a dropdown, and `navigate` sends the user to another admin route.

That last one is the trick I promised. When an action has no `endpoint`, Admin Next fires a `page-action` event at your component instead, so you handle it in JavaScript:

```javascript
connectedCallback() {
  this.attachShadow({ mode: 'open' });
  this.addEventListener('page-action', (e) => {
    if (e.detail.id === 'export-csv') this._exportCsv();
  });
  this._render();
  this._loadData();
}
```

## What About Tabs?

The outline I started from had a whole section on tabbed pages, with some tabs being blueprints and some being custom components in the same page. I'll be straight with you: that hybrid doesn't exist. There's no tabs array in the page definition, and no mode where Admin Next stitches a blueprint tab next to a component tab.

What you actually have is two honest options.

If you're in **blueprint mode**, tabs come for free from the blueprint itself. Grav blueprints have always supported tab sections, and Admin Next renders them as tabs just like the page editor does. Group your fields into tabs in the YAML and you're done.

If you're in **component mode**, the tabs are yours to build. That sounds like more work than it is. Both Yeti Search Pro and SEO Magic build their own tab strips in plain JavaScript inside the page component, swapping the content area when you click. You're rendering a few buttons and a content div, not adopting a framework.

So how do Yeti Search Pro and SEO Magic give you a rich dashboard *and* a normal settings form without a hybrid page? They don't try. The dashboard is a component page, and the plain settings stay where settings have always lived, on the regular plugin configuration page. The link between them is that `options` action up in the header, the one with `navigate: '/plugins/seo-magic'`. Click it and you jump to the standard config form. Two purpose-built screens, each rendered the way it's best rendered, one button connecting them. That's the pattern to copy.

## The Filesystem Shortcut

If your page definition is static, you can skip the PHP event entirely. Drop a file in `admin-next/pages/` and the API infers the rest:

- `admin-next/pages/my-plugin.yaml` gives you a blueprint-mode page (the YAML is the definition).
- `admin-next/pages/my-plugin.js` gives you a component-mode page, with the title auto-generated from the slug.

You'll still want the event when the definition depends on config or the current user (gating the page, building actions conditionally), since the event handler receives `$event['user']`. But for a simple dashboard, the bare `.js` file is all it takes.

## Reference Implementations

Both of these are component-mode pages you can read top to bottom:

- **Yeti Search Pro** registers a `fa-search` sidebar entry gated on `api.yetisearch-pro.view`, and a component page that builds its own tabs for index management, the search tester, and analytics. Its single header action is an `options` button that navigates to the plugin config page. A good model for a data-heavy dashboard.
- **SEO Magic** registers a `fa-chart-line` entry and a component page with the split-button, download, and navigate actions shown above. It also ships custom field types (in `admin-next/fields/`) that appear inside its config blueprint, so it's a nice example of one plugin using several Admin Next integration points together.

If you have either installed, the page components live at `admin-next/pages/{slug}.js` in each plugin. Read them next to this post.

## A Few Things Worth Getting Right

- **Gate the page the same way you gate the sidebar.** A hidden sidebar entry doesn't stop someone typing the route. Check the permission in `onApiPluginPageInfo` too, and remember that in API context you read permissions with `$user->get('access.api.my-plugin.view')`, not `$user->authorize()`.
- **Read the theme tokens.** Use `var(--foreground)`, `var(--background)`, `var(--border)`, `var(--primary)` and the rest so your page follows light and dark mode without you maintaining two palettes.
- **Handle loading and error states.** Your component fetches its own data, so render a sensible empty state first and don't assume the fetch succeeded.
- **Keep it responsive.** Admin Next runs down to phone widths and so should your page. Tables especially need a plan for narrow screens.
- **Use `window.__GRAV_DIALOGS.confirm()` for anything destructive,** never the native `confirm()`. It matches the rest of the admin and handles focus and keyboards properly.

## Quick Links and Help

- **Learn site reference:** [Custom Admin Pages](https://learn.getgrav.org/2/api/developer-guide).
- **Previous post in the series:** [Admin Next Custom Form Fields](https://getgrav.org/blog/grav-2-dev-admin-next-custom-fields).
- **The API endpoints your pages talk to:** [API Integration for Plugins](https://getgrav.org/blog/grav-2-dev-api-integration).
- **Discord:** [chat.getgrav.org](https://chat.getgrav.org) if something isn't rendering the way you expect.

A custom page is the moment your plugin stops feeling like a guest in the admin and starts feeling like part of it. Pick the mode that fits the screen, lean on blueprint mode whenever a form will do, and reach for component mode when you genuinely need the canvas. The two reference plugins between them cover almost everything you'll run into.

Andy

---

 Important

**Next in the developer series:** [Grav 2.0 Developer Guide: Admin Next Panels & Menu Bar](#)

 ![Andy Miller](https://getgrav.org/user/themes/event-horizon/images/authors/andy.png) 

Andy Miller

 Creator and lead developer of Grav CMS, with over 30 years in software development and 20+ years in open source, dating back to his years as a core member of the Joomla CMS development team. 

 [Threads](https://www.threads.net/@rhukster) [Bluesky](https://bsky.app/profile/rhuk.bsky.social) 

 [  Back to blog ](https://getgrav.org/blog) [  ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fgetgrav.org%2Fblog%2Fgrav-2-dev-admin-next-custom-pages&text=Grav%202.0%20Developer%20Guide%3A%20Admin%20Next%20Custom%20Pages) [   ](https://getgrav.org/blog/grav-2-dev-admin-next-custom-pages) 

##  Comments 

No comments yet — start the discussion below.

 [ Log in to join the discussion](https://getgrav.org/login?return=%2Fblog%2Fgrav-2-dev-admin-next-custom-pages)

← NEWER

The Grav API: The Foundation of 2.0

[← NEWER The Grav API: The Foundation of 2.0](https://getgrav.org/blog/grav-2-api)

OLDER →

Admin2 Goodies

[OLDER → Admin2 Goodies](https://getgrav.org/blog/admin2-goodies)

Related posts

## Keep reading

 comparison OCT 16 wordpress grav2 

### Grav vs WordPress: An Honest Comparison

I co-founded Joomla, I created Grav, and I've spent more than twenty years building sites on PHP content management systems. So I get asked one question more than any oth…

 ![Andy Miller](https://getgrav.org/user/themes/event-horizon/images/authors/andy.png) Andy Miller  10 mins  

[Grav vs WordPress: An Honest Comparison](https://getgrav.org/blog/grav-vs-wordpress)

 grav2 JUN 20 release update 

### Grav 2.0 Released!

Today, Grav 2.0 is stable. I'm thrilled to finally write those words. This is the biggest release in the project's history, and it's been a long road to get here. The fir…

 ![Andy Miller](https://getgrav.org/user/themes/event-horizon/images/authors/andy.png) Andy Miller  7 mins  

[Grav 2.0 Released!](https://getgrav.org/blog/grav-2-stable-released)

 grav2 JUN 17 security twig content 

### Grav 2.0: Twig in Content and the New Security Sandbox

If you've moved a site to Grav 2.0 and a bit of {{ ... }} you had sitting in a page suddenly shows up as literal text instead of rendering, this post is for you. We chang…

 ![Andy Miller](https://getgrav.org/user/themes/event-horizon/images/authors/andy.png) Andy Miller  10 mins  

[Grav 2.0: Twig in Content and the New Security Sandbox](https://getgrav.org/blog/grav-2-twig-content-security)

---

## Navigation

- Parent: [Grav - Development Blog](https://getgrav.org/blog.md)
- Previous: [The Grav API: The Foundation of 2.0](https://getgrav.org/blog/grav-2-api.md)
- Next: [Admin2 Goodies](https://getgrav.org/blog/admin2-goodies.md)
