Admin Widgets

Admin widgets are modular UI components displayed on the admin dashboard. They allow you to present key metrics (e.g., total users, active subscribers) and interactive tools (like language switchers or quick nav menus) in a dynamic, organized way.

Widgets are categorized into two types:

• Dashboard Widgets – Displayed in the main admin dashboard (e.g., Total Earnings, Active Users).
• Header Widgets – Rendered in the top header bar for quick actions (e.g., language toggle, fullscreen mode).

Registering a Widget

Widgets are registered using the WidgetManager, available via the Qoraiche\Peak\Facades\Widget facade.

Example: Register a Header Widget in a Service Provider

$widget = [
    'slug' => 'quick-navigation-header-widget',
    'title' => __('Quick Navigation'),
    'icon' => 'Menu',
    'component' => QuickNavigationHeaderWidget::class,
    'order' => 1,
    'group' => 'header',
];

Qoraiche\Peak\Facades\Widget::register($widget);

You can also register multiple widgets at once:

Qoraiche\Peak\Facades\Widget::registerMany([$widget1, $widget2]);

WidgetManager

All widget logic is centralized in Qoraiche\Peak\Services\WidgetManager. It provides methods to:

register() – Register a single widget

registerMany() – Register multiple widgets

unregister() – Remove a widget by slug

hook() – Dynamically modify widget config via callback

all() – Get sorted widgets per group and user permissions

get(), data(), instance() – Retrieve widgets and their data

Widgets must extend the abstract BaseWidget class and implement the data() method.

Example: Total Active Users Widget

Backend class app/Services/Widgets/TotalActiveUsersWidget.php

use Inertia\Inertia;
use Qoraiche\Peak\Services\Admin\AdminOverviewService;

class TotalActiveUsersWidget extends BaseWidget
{
    public function __construct(AdminOverviewService $adminOverviewService)
    {
        parent::__construct($adminOverviewService);
    }

    public function data(): array
    {
        [$adminOverviewService] = $this->services;

        return [
            'totalActiveUsersCount' => Inertia::defer(fn() => number_format($adminOverviewService->getActiveUsersCount()), 'widgets'),
        ];
    }
}

Frontend component resources/js/Layouts/Admin/Widgets/TotalActiveUsersWidget.vue

<template>
  <StatsWidget :deferred="lazy" deferred-data="totalActiveUsersCount">
    <template #icon>
      <DynamicLucideIcon v-if="icon" :icon="icon" class="stroke-blue-500" />
    </template>
    <template #label>{{ __(title) }}</template>
    <template #data>{{ totalActiveUsersCount }}</template>
  </StatsWidget>
</template>

<script setup>
import StatsWidget from "@peak/Components/Admin/StatsWidget.vue";
import DynamicLucideIcon from "@peak/Components/Admin/DynamicLucideIcon.vue";

defineProps({
  totalActiveUsersCount: [Number, String],
  title: String,
  lazy: Boolean,
  icon: String,
});
</script>

Register it in the loader: resources/js/Layouts/Admin/Widgets/loader.js:

export const widgetComponents = {
TotalActiveUsersWidget: () => import("@peak/Layouts/Admin/Widgets/TotalActiveUsersWidget.vue"),
// more widgets...
};

Example: Header Widget – Fullscreen Toggle

Backend class

Qoraiche\Peak\Services\Widgets\Header\ToggleFullScreenHeaderWidget.php:

class ToggleFullScreenHeaderWidget extends BaseWidget
{
    public function data(): array
    {
        return [];
    }
}

Registration:

$widget = [
    'slug' => 'toggle-fullscreen-header-widget',
    'title' => __('Fullscreen Mode'),
    'icon' => 'Maximize',
    'component' => ToggleFullScreenHeaderWidget::class,
    'order' => 3,
    'group' => 'header',
];

Qoraiche\Peak\Facades\Widget::register($widget);

Vue component resources/js/Layouts/Admin/HeaderWidgets/ToggleFullScreenHeaderWidget.vue:

<template>
  <button
    v-tooltip="__(title)"
    class="-m-2.5 w-11 h-11 hidden md:flex justify-center items-center text-gray-400 hover:text-gray-500 rounded-full bg-green-50 hover:bg-green-100 transition duration-300"
    @click="toggleFullScreen"
    type="button"
  >
    <DynamicLucideIcon v-if="icon" :icon="icon" />
  </button>
</template>

<script setup>
import DynamicLucideIcon from "@/Themes/Breeze/Components/DynamicLucideIcon.vue";

defineProps({ title: String, icon: String });

function toggleFullScreen() {
  const elem = document.documentElement;

  if (!document.fullscreenElement) {
    elem.requestFullscreen().catch(err => alert(`Error: ${err.message}`));
  } else {
    document.exitFullscreen();
  }
}
</script>

Permissions & Roles

Each widget can be restricted to users based on:

• role – Show widget only to users with a specific role.
• permission – Show widget only if user has specific permission.

This is handled automatically by WidgetManager::filterWidgetByPermissions().