# Plugin Development
> #### Experimental {: .warning}
>
> The Plugin API is `@experimental`. Breaking changes may occur in minor versions until
> this notice is removed. Pin your `phoenix_filament` dependency to a specific version
> when building plugins.
Plugins let you extend a PhoenixFilament panel with custom navigation, live routes,
dashboard widgets, and lifecycle hooks — using the exact same API that PhoenixFilament
uses internally.
## Quick Start
```elixir
defmodule MyApp.AnalyticsPlugin do
use PhoenixFilament.Plugin
@impl true
def register(_panel, _opts) do
%{
nav_items: [
nav_item("Analytics",
path: "/analytics",
icon: "hero-chart-bar",
nav_group: "Reports")
],
routes: [
route("/analytics", MyAppWeb.AnalyticsLive, :index)
]
}
end
end
```
Register it in your panel:
```elixir
defmodule MyAppWeb.Admin do
use PhoenixFilament.Panel, path: "/admin"
plugins do
plugin MyApp.AnalyticsPlugin
end
end
```
## `use PhoenixFilament.Plugin`
Using this macro:
1. Adds `@behaviour PhoenixFilament.Plugin` to your module
2. Imports `nav_item/2` and `route/3` helper functions
## Callbacks
### `register/2` (required)
Called at compile time when the panel resolves its plugin list. Returns a map describing
what the plugin contributes to the panel.
```elixir
@impl true
def register(panel_module, opts) do
%{
nav_items: [...],
routes: [...],
widgets: [...],
hooks: [...]
}
end
```
Arguments:
- `panel_module` — the Panel module that is registering this plugin
- `opts` — the keyword list passed to `plugin MyPlugin, key: value`
All keys in the returned map are optional. Omit any key you do not need.
#### `:nav_items`
Navigation entries added to the panel sidebar. Build them with `nav_item/2`:
```elixir
nav_item("Analytics",
path: "/analytics",
icon: "hero-chart-bar",
nav_group: "Reports")
```
`nav_item/2` options:
| Key | Type | Description |
|-----|------|-------------|
| `path:` | string | URL path (relative to panel root) |
| `icon:` | string | Heroicon name |
| `nav_group:` | string | Sidebar group heading |
#### `:routes`
Live routes added to the panel's `live_session`. Build them with `route/3`:
```elixir
route("/analytics", MyAppWeb.AnalyticsLive, :index)
route("/analytics/:id", MyAppWeb.AnalyticsLive, :show)
```
`route/3` arguments:
1. Path string (relative to the panel's `scope` path)
2. LiveView module
3. Live action atom
All routes registered via plugins automatically inherit the panel's `on_mount` hooks,
session name, and layout.
#### `:widgets`
Dashboard widgets contributed by the plugin:
```elixir
widgets: [
%{module: MyApp.AnalyticsWidget, sort: 5, column_span: 6}
]
```
Widget map keys:
| Key | Default | Description |
|-----|---------|-------------|
| `module` | required | LiveComponent module |
| `sort` | `0` | Dashboard rendering order (ascending) |
| `column_span` | `12` | Grid column span (1–12) |
The widget module must implement one of the widget behaviours:
`PhoenixFilament.Widget.StatsOverview`, `PhoenixFilament.Widget.Chart`,
`PhoenixFilament.Widget.Table`, or `PhoenixFilament.Widget.Custom`.
#### `:hooks`
Lifecycle hooks called at various points in the panel LiveView:
```elixir
hooks: [
{:handle_event, &MyApp.AnalyticsPlugin.handle_event/3},
{:handle_info, &MyApp.AnalyticsPlugin.handle_info/2},
{:handle_params, &MyApp.AnalyticsPlugin.handle_params/3},
{:after_render, &MyApp.AnalyticsPlugin.after_render/1}
]
```
Hook function signatures:
```elixir
# handle_event: called before the panel's handle_event
def handle_event(event, params, socket), do: {:cont, socket}
# handle_info: called before the panel's handle_info
def handle_info(message, socket), do: {:cont, socket}
# handle_params: called before the panel's handle_params
def handle_params(params, uri, socket), do: {:cont, socket}
# after_render: called after each render
def after_render(socket), do: socket
```
Return `{:cont, socket}` to allow the default handler to proceed, or `{:halt, socket}`
to stop further processing.
### `boot/1` (optional)
Called at runtime on each panel LiveView `mount`. Receives the socket after the panel's
own `on_mount` hooks have run. Returns the modified socket.
```elixir
@impl true
def boot(socket) do
user_id = socket.assigns.current_user.id
# Subscribe to a PubSub topic
Phoenix.PubSub.subscribe(MyApp.PubSub, "analytics:#{user_id}")
# Add assigns available throughout the panel session
Phoenix.Component.assign(socket, :analytics_enabled, true)
end
```
`boot/1` cannot halt the mount — authentication is the Panel's responsibility.
## Plugin Options
Pass configuration to your plugin from the panel:
```elixir
plugins do
plugin MyApp.AnalyticsPlugin,
nav_group: "Reports",
show_realtime: true
end
```
Access options in `register/2`:
```elixir
def register(_panel, opts) do
group = opts[:nav_group] || "Analytics"
show_realtime = opts[:show_realtime] || false
%{
nav_items: [
nav_item("Analytics", path: "/analytics", nav_group: group)
] ++ if(show_realtime, do: [nav_item("Live", path: "/analytics/live", nav_group: group)], else: [])
}
end
```
## Complete Plugin Example
```elixir
defmodule MyApp.AuditLogPlugin do
use PhoenixFilament.Plugin
@impl true
def register(_panel, opts) do
group = opts[:nav_group] || "System"
%{
nav_items: [
nav_item("Audit Log",
path: "/audit",
icon: "hero-clipboard-document-list",
nav_group: group)
],
routes: [
route("/audit", MyAppWeb.AuditLive, :index),
route("/audit/:id", MyAppWeb.AuditLive, :show)
],
widgets: [
%{module: MyApp.RecentAuditWidget, sort: 10, column_span: 12}
],
hooks: [
{:handle_info, &__MODULE__.handle_info/2}
]
}
end
@impl true
def boot(socket) do
if Map.has_key?(socket.assigns, :current_user) do
Phoenix.PubSub.subscribe(MyApp.PubSub, "audit_log")
end
socket
end
def handle_info({:audit_event, event}, socket) do
# Update live audit count in sidebar badge, etc.
updated = update_in(socket.assigns[:audit_count] || 0, &(&1 + 1))
{:cont, Phoenix.Component.assign(socket, :audit_count, updated)}
end
def handle_info(_msg, socket), do: {:cont, socket}
end
```
## Testing Your Plugin
Use ExUnit with `use ExUnit.Case`:
```elixir
defmodule MyApp.AuditLogPluginTest do
use ExUnit.Case, async: true
describe "register/2" do
test "returns nav_items and routes" do
result = MyApp.AuditLogPlugin.register(MyAppWeb.Admin, [])
assert [nav_item] = result.nav_items
assert nav_item.label == "Audit Log"
assert nav_item.path == "/audit"
assert [route1, route2] = result.routes
assert route1.path == "/audit"
assert route1.live_action == :index
end
test "respects nav_group option" do
result = MyApp.AuditLogPlugin.register(MyAppWeb.Admin, nav_group: "Security")
[nav_item] = result.nav_items
assert nav_item.nav_group == "Security"
end
end
describe "boot/1" do
test "assigns analytics_enabled" do
socket = %Phoenix.LiveView.Socket{assigns: %{current_user: %{id: 1}}}
result = MyApp.AuditLogPlugin.boot(socket)
# boot modifies the socket — assert your expected changes
assert result != nil
end
end
end
```
## Stability Contract
| Version | Status |
|---------|--------|
| v0.1.x | `@experimental` — breaking changes possible in minor versions |
| v0.2+ | Stabilize based on community feedback |
| v1.0 | Stable, semver-protected |
Pin your dependency to a patch version while the API is experimental:
```elixir
{:phoenix_filament, "~> 0.1.0"}
```
