# piral-dashboard

> Plugin for creating a centralized dashboard in Piral.

Latest version **1.12.4** (published 2026-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install piral-dashboard
pnpm add piral-dashboard
yarn add piral-dashboard
bun add piral-dashboard
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.12.4 |
| Published | 2026-09-11 |
| First published | 2019-10-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 46.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1933 |
| Author | smapiot |
| Maintainers | florianrappl, manuel.roemer, lschoett |
| Keywords | piral, pilet-api, smapiot, portal, modules, api, plugin, plugin-component, dashboard, tiles |

## Links

- npm: https://www.npmjs.com/package/piral-dashboard
- Repository: https://github.com/smapiot/piral
- Homepage: https://piral.io
- Issues: https://github.com/smapiot/piral/issues
- npm.io page: https://npm.io/package/piral-dashboard

## Recent versions

- 1.12.4 (latest) — 2026-09-11
- 1.12.4-beta.fb90a9c (next) — 2026-10-21
- 0.15.0-alpha.4409 (canary) — 2022-07-07
- 1.12.4-beta.b76e5ae — 2026-10-21
- 1.12.4-beta.5c7192f — 2026-10-17
- 1.12.4-beta.ef95646 — 2026-10-17
- 1.12.4-beta.0bc4ce7 — 2026-10-17
- 1.12.4-beta.cf72637 — 2026-10-17
- 1.12.4-beta.92532b1 — 2026-10-16
- 1.12.4-beta.4f77727 — 2026-10-04
- 1.12.4-beta.6cb8b4e — 2026-10-04
- 1.12.4-beta.dc8413a — 2026-10-04
- 1.12.4-beta.80d7277 — 2026-09-29
- 1.12.4-beta.d019a51 — 2026-09-29
- 1.12.4-beta.6c244e5 — 2026-09-09
- … 1140 more at https://npm.io/package/piral-dashboard/versions

## README

[![Piral Logo](https://github.com/smapiot/piral/raw/main/docs/assets/logo.png)](https://piral.io)

# [Piral Dashboard](https://piral.io) · [![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/smapiot/piral/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/piral-dashboard.svg?style=flat)](https://www.npmjs.com/package/piral-dashboard) [![tested with vitest](https://img.shields.io/badge/tested_with-vitest-99424f.svg)](https://vitest.dev/) [![Community Chat](https://img.shields.io/discord/1222632475449229352)](https://discord.gg/kKJ2FZmK8t)

This is plugin that only has a peer dependency to `piral-core`. What `piral-dashboard` brings to the table is a set of Pilet API extensions that can be used with `piral` or `piral-core`.

## Why and When

Many portal and tool applications come with a dashboard view that easily allows getting an overview over the most interesting pieces of functionality and information. This plugin allows creating dashboard pages that contain components registered as "tiles". The layout and behavior of these can be fully configured. The standard options include variable rows, columns, and resize properties.

Alternatives: Use extensions to define this generically without the need for a plugin. Place each dashboard in its own extension slot registering components dynamically for these.

## Video

We also have a video for this plugin:

@[youtube](https://youtu.be/ycZLPRaoLAQ)

## Documentation

The following functions are brought to the Pilet API.

### `registerTile()`

Adds the definition of a tile to the app shell. Optionally specifies display characteristics like the initial rows, initial columns, or if the tile can be resized by the user.

If the first argument is a string a named tile is registered. A named tile can also be removed.

### `unregisterTile()`

Removes a tile from the app shell. This requires a named tile.

## Usage

::: summary: For pilet authors

You can use the `registerTile` function from the Pilet API to add a new tile in the app shell.

**Note**: When the first argument is a string we call it a *named* tile.

Example use:

```ts
import { PiletApi } from '<name-of-piral-instance>';
import { MyTile } from './MyTile';

export function setup(piral: PiletApi) {
  piral.registerTile(MyTile);
}
```

You can use the `unregisterTile` function from the Pilet API to remove a previously added tile from the app shell.

**Note**: You'll need to have added a *named* tile in order to be able to remove it.

Example use:

```ts
import { PiletApi } from '<name-of-piral-instance>';
import { MyTile } from './MyTile';

export function setup(piral: PiletApi) {
  // register with a name
  piral.registerTile('first', MyTile);
  // and unregister; maybe some time later?
  piral.unregisterTile('first');
}
```

:::

::: summary: For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import `createDashboardApi` from the `piral-dashboard` package.

```ts
import { createDashboardApi } from 'piral-dashboard';
```

The integration looks like:

```ts
const instance = createInstance({
  // important part
  plugins: [createDashboardApi()],
  // ...
});
```

Via the options the `defaultPreferences` and the global/initially available `tiles` can be defined.

Consider for example:

```ts
const instance = createInstance({
  // important part
  plugins: [createDashboardApi({
    defaultPreferences: {
      initialColumns: 2,
      initialRows: 2,
      resizable: true,
    },
    tiles: [
      {
        component: MyTeaserTile,
        preferences: {
          initialColumns: 2,
          initialRows: 4,
        },
      },
    ],
  })],
  // ...
});
```

By default, the dashboard is located at the homepage (`/`). You can change this via the `routes` setting:

```ts
const instance = createInstance({
  // important part
  plugins: [createDashboardApi({
    routes: ['/dashboard'],
  })],
  // ...
});
```

Or alternatively, don't use any route for it and just reference the `Dashboard` component on any page or within the layout.

```ts
// for the instance
const instance = createInstance({
  // important part
  plugins: [createDashboardApi({
    routes: [],
  })],
  // ...
});


// in some component, maybe even in the layout
import { Dashboard } from 'piral-dashboard';

// then use: <Dashboard />
```

### Customizing

You can customize the available tiles and their options.

```ts
import type {} from 'piral-dashboard';

declare module 'piral-dashboard/lib/types' {
  interface PiralCustomTilePreferences {
    category?: string;
  }
}

// now registerTile(() => null, { category: 'general' }) is strongly typed in pilets
```

:::

## License

Piral is released using the MIT license. For more information see the [license file](./LICENSE).

---
_Source: https://npm.io/package/piral-dashboard · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._