Single source of truth for Birkly CMS documentation

How to set the sidebar icon for a plugin via plugin.json → navigation.icon (or sidebar.icon in the admin shelf metadata).

A plugin that adds an admin sidebar item declares navigation in plugin.json, and its icon field sets the glyph beside the plugin name. Use a registry name from the Birch icon set, such as "card", "calendar", "users", "zap" or "template". The admin draws it as a 13 px pixel icon that plays its hover gesture, exactly like Dashboard, Content and Settings. A plugin's own inline SVG still works as a fallback: it is sized to the same 13 px box, but it has no gesture.

Beginner

When your plugin appears in the admin sidebar, a small icon sits beside its label. You choose that icon in plugin.json:

{
  "name": "My Plugin",
  "navigation": {
    "name": "My Plugin",
    "page": "my-plugin",
    "icon": "calendar"
  }
}

Registry name (recommended). Pick a name from the icon set in Admin design language § Icons. The sidebar draws it in the same pixel style as core items, and it moves when the row is hovered or focused: a calendar hops, a bell rings, a truck bounces.

Custom inline SVG (fallback). If nothing fits, set icon to a full <svg>…</svg> string using currentColor. It is shown at 13 × 13 px. For a crisp result, draw it on a 13 × 13 viewBox in whole cells with shape-rendering="crispEdges".

If you omit icon, or give a name that doesn't exist, the sidebar shows the default plugin icon (sliders).

Advanced users

navigation block

FieldPurpose
nameSidebar label
pageAdmin page slug (matches your registered admin route)
iconRegistry name or inline SVG string

Plugins that register through the admin shelf (register_plugin_admin_meta()) set the same value as sidebar.icon; the shelf entry wins over plugin.json:

register_plugin_admin_meta('my-plugin', [
    'title' => '@i18n:plugins.my_plugin.title',
    'root_page' => 'my-plugin',
    'sidebar' => ['show' => true, 'label' => '@i18n:plugins.my_plugin.title', 'order' => 50, 'icon' => 'calendar'],
]);

Rendering

birkly_nav_icon($icon) in core/icons.php renders the value. It is used by admin/partials/sidebar.php and by the get_navigation action of api/plugins.php.

ValueResult
A registry name ([a-z0-9-]+) that resolvesbirkly_icon($name, ['class' => 'nav-icon']): a 13 px Birch icon with its gesture
A string starting with <svgReturned as is. The sidebar sizes it to var(--icon)
Anything else, or emptyThe default plugin icon

Pre-Birch names (gear, shopping-bag, file-text) still resolve through aliases, but the aliases are going away. Use the Birch name instead (sliders, bag, content); the full table is in Plugin admin styling § Icon names.

Listing names: birkly_icon_names() in PHP, Birkly.iconNames in JS.

Choosing an icon

PluginIcon
Commercecard
Eventscalendar
Userusers
Automationzap
Studiotemplate

Pick the icon that names what the plugin is, not a brand mark. Don't reuse an icon that a core item already shows (dashboard, content, media, sparkle for Discovery, bag for the Hub, sliders for Settings, help). If no registry icon fits, ship inline SVG for that plugin only. To contribute a reusable icon to core, add its grid to core/icon_data.php and run php scripts/build-icons.php.

Icons inherit currentColor from the sidebar row, so check them in light and dark.