👀 Get a glimpse of Kirby 5 Learn more
Skip to content

Panel view buttons

Kirby 5 adds new extensions that allow plugin developers to add custom view buttons to most views of the Panel (e.g. page, site, file, user, language). These buttons can be added alongside the default buttons, such as the preview button or settings dropdown button.

There are different ways to define a custom button: in a blueprint, in the config.php, in a Panel area or as a full custom Vue component.

In a blueprint

To select which buttons to show on a particular view you can set the buttons option in the corresponding blueprint:

site/blueprints/pages/note.yml
buttons:
  - preview
  - settings

This way, you can reference existing buttons by name and decide which ones to include and in what order.

A custom Vue component

Some custom buttons might need more options, more interactivity, more glamour than <k-view-button> offers. Those can create their own Vue component in your plugin's JavaScript file:

site/plugins/your-plugin/index.js
panel.plugin("getkirby/custom-view-buttons", {
  viewButtons: {
    applause: {
      template: `<k-button icon="heart" variant="filled" theme="love" size="sm" @click="applause">Applause</k-button>`,
      methods: {
        applause() {
          alert("👏");
        },
      },
    },
  },
});

You can then reference it by name in your blueprints or config file. Or if you want to pass props as well:

buttons:
  - preview
  - settings
  - applause

Even Better View buttons

Building upon the foundation from Alpha 1, you can now also define new custom buttons directly in your blueprints:

buttons:
  - preview
  - settings
  analytics:
    icon: chart
    text: Analytics
    link: https://my-analytics.com/for/this/page
    theme: aqua-icon

You can also pass custom Vue component and its props.

buttons:
  - preview
  - settings
  analytics:
    component: k-analytics-view-button
    props:
      funnel: cpc

The available options are based on the k-view-button component (better docs will follow until the final release).

In the config.php

Similarly to the blueprints, buttons can now be defined in your config file. In this case, not for a specific template but in general for the different view types (page, file, site, user, system, ...):

site/config/config.php
'panel' => [
  'viewButtons' => [
    'site' => [
      'preview',
      'newsletter' => [
        'icon'   => 'heart',
        'text'   => 'Kosmos',
        'theme'  => 'purple-icon',
        'target' => '_blank',
        'link'   => 'https://getkirby.com'
      ],
      'analytics-dropdown' => [
        'props' => [
          'icon'     => 'chart',
          'text'     => 'Analytics',
          'dropdown' => 'my/analytics/dropdown/route'
        ]
      ],
      'promote-component' => [
        'component' => 'my-custom-component',
        'props' => [
          'channel' => 'instagram'
        ]
      ]
    ]
  ]
]

What you can see above are three different ways to define a custom button:

  • The first one directly defines the options. It's a shortcut that assumes these are the props for the k-view-button component.
  • In the second example, they are already wrapped inside the props key. But no component is defined, so k-view-button is used as well.
  • In the third example, we actually define a custom Vue component that should be used instead, alongside passing props to this component.

In a Panel area

If you do not want to define just one button via the config, but reuse it (or even ship it as part of your plugin), you can add them to the Panel area extension:

site/plugins/your-plugin/index.php
Kirby::plugin('custom/buttons', [
  'areas' => [
    'todos' => function () {
      return [
        'buttons' => [
          'todos.add' => function () {
            return [
              'props' => [
                'icon'   => 'add',
                'dialog' => 'todos/create'
              ]
            ];
          }
        ]
      ];
    }
  ]
]);

You have the same options for your return value: full component-props array or just props on top-level. In addition, you can also return directly a Kirby\Panel\Ui\Button\ViewButton object.