@spec apply_hidden_admin_tabs([PhoenixKit.Dashboard.Tab.t()]) :: [
  PhoenixKit.Dashboard.Tab.t()
]

Drops the tabs listed in :hidden_admin_tabs from tabs.

Public so the filter can be tested as the pure function it is — this is the exact composition load_admin_defaults_internal/0 applies to AdminTabs.default_tabs/0.

@spec broadcast_refresh() :: :ok

Broadcasts a full tab list refresh to all subscribers.

@spec broadcast_update(PhoenixKit.Dashboard.Tab.t()) :: :ok

Broadcasts a tab update to all subscribers.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec clear_tab_attention(atom()) :: :ok

Clears attention animation from a tab.

@spec get_admin_tabs(keyword()) :: [PhoenixKit.Dashboard.Tab.t()]

Gets admin-level tabs, filtered by permission and module-enabled status.

Options

• :scope - The current scope (for permission and visibility filtering)
• :include_hidden - Include tabs that would be hidden (default: false)

@spec get_groups() :: [PhoenixKit.Dashboard.Group.t()]

Gets all registered groups, sorted by priority.

@spec get_subtabs(
  atom(),
  keyword()
) :: [PhoenixKit.Dashboard.Tab.t()]

Gets all subtabs for a given parent tab ID.

Examples

Registry.get_subtabs(:orders)
# => [%Tab{id: :pending_orders, parent: :orders, ...}, ...]

@spec get_tab(atom()) :: PhoenixKit.Dashboard.Tab.t() | nil

Gets a specific tab by ID.

@spec get_tabs(keyword()) :: [PhoenixKit.Dashboard.Tab.t()]

Gets all registered tabs, sorted by priority.

Options

• :scope - The current scope (for visibility filtering)
• :level - Filter by tab level: :admin, :user, or nil for all
• :path - The current path (for active state detection)
• :include_hidden - Include tabs that would be hidden (default: false)

Examples

Registry.get_tabs()
Registry.get_tabs(scope: scope, level: :user)
Registry.get_tabs(scope: scope, level: :admin)

@spec get_tabs_in_group(
  atom(),
  keyword()
) :: [PhoenixKit.Dashboard.Tab.t()]

Gets all tabs in a specific group.

@spec get_tabs_with_active(
  String.t(),
  keyword()
) :: [map()]

Gets all tabs with their active state for the given path.

Returns tabs with an additional :active key set based on path matching.

@spec get_top_level_tabs(keyword()) :: [PhoenixKit.Dashboard.Tab.t()]

Gets only top-level tabs (tabs without a parent).

Options

Same as get_tabs/1.

Examples

Registry.get_top_level_tabs()
# => [%Tab{id: :orders, parent: nil, ...}, ...]

@spec get_user_tabs(keyword()) :: [PhoenixKit.Dashboard.Tab.t()]

Gets user-level tabs.

Options

• :scope - The current scope (for visibility filtering)
• :include_hidden - Include tabs that would be hidden (default: false)

@spec has_subtabs?(atom()) :: boolean()

Checks if a tab has any subtabs.

Examples

Registry.has_subtabs?(:orders)
# => true

@spec hidden_admin_tabs() :: [atom()]

Admin tab ids the host has hidden:

config :phoenix_kit, hidden_admin_tabs: [:admin_locations]

"I want this module's data but not its UI" is an ordinary need — a host may install phoenix_kit_locations purely as a data layer and never want its admin section.

Applied during registry init, not by unregister_tab/1. That function mutates GenServer state, and the registry rebuilds from AdminTabs.default_tabs/0 whenever it initialises — so a supervisor restart would silently resurrect the hidden tabs mid-flight, with nothing to indicate it had happened. Applying it at the rebuild is what makes hiding survive.

Hiding is cosmetic: it removes the sidebar entry, not the route or the permission. Use permissions to control access.

@spec initialized?() :: boolean()

Checks if the registry has been initialized.

@spec load_admin_defaults() :: :ok

Loads admin default tabs.

Called during initialization.

@spec load_defaults() :: :ok

Loads the default PhoenixKit tabs (Dashboard, Settings).

Called during initialization and can be used to reset to defaults.

@spec load_from_config() :: :ok

Loads tabs from application configuration.

Reads from :phoenix_kit, :user_dashboard_tabs config key.

@spec path_for_live_view(module()) :: String.t()

The admin path of the tab that declares view as its live_view, or "/admin" when nothing claims it.

Sidebar active-state reads assigns[:url_path], which the kit's on_mount chain fills in from a :handle_params hook. Two kinds of LiveView never get it: one rendered via live_render/3 (an embed has no handle_params lifecycle at all) and a host LV that renders admin chrome without going through that chain. Both used to render with no tab highlighted and nothing to suggest why. A tab already knows its own path, so ask it.

@spec pubsub_topic() :: String.t()

Gets the PubSub topic for tab updates.

LiveViews can subscribe to this topic to receive real-time tab updates.

Example

def mount(_params, _session, socket) do
  if connected?(socket) do
    Phoenix.PubSub.subscribe(PubSubHelper.pubsub(), Registry.pubsub_topic())
  end
  {:ok, socket}
end

def handle_info({:tab_updated, tab}, socket) do
  # Handle tab update
  {:noreply, socket}
end

@spec register(atom(), PhoenixKit.Dashboard.Tab.t() | [PhoenixKit.Dashboard.Tab.t()]) ::
  :ok

Registers tabs for an application namespace.

Examples

Registry.register(:my_app, [
  Tab.new!(id: :home, label: "Home", path: "", icon: "hero-home"),
  Tab.new!(id: :orders, label: "Orders", path: "orders")
])

# Register a single tab
Registry.register(:my_app, Tab.new!(id: :settings, label: "Settings", path: "settings"))

@spec register_from_config(atom(), [map()] | [keyword()]) :: :ok | {:error, term()}

Registers tabs from a map/keyword configuration.

Useful for registering tabs from config files.

Examples

Registry.register_from_config(:my_app, [
  %{id: :home, label: "Home", path: "", icon: "hero-home"},
  %{id: :orders, label: "Orders", path: "orders"}
])

@spec register_groups([PhoenixKit.Dashboard.Group.t() | map()]) :: :ok

Registers tab groups.

Examples

Registry.register_groups([
  %{id: :main, label: nil, priority: 100},
  %{id: :farm, label: "Farm Management", priority: 200},
  %{id: :account, label: "Account", priority: 900}
])

@spec set_tab_attention(atom(), atom()) :: :ok

Sets an attention animation on a tab.

Examples

Registry.set_tab_attention(:alerts, :pulse)
Registry.set_tab_attention(:notifications, :bounce)

Starts the Registry GenServer.

This is typically called by the PhoenixKit supervisor.

@spec unregister(atom()) :: :ok

Unregisters all tabs for a namespace.

@spec unregister_tab(atom()) :: :ok

Unregisters a specific tab by ID.

@spec update_tab(atom(), map()) :: :ok

Updates an existing tab's attributes.

Examples

Registry.update_tab(:admin_dashboard, %{label: "Home", icon: "hero-house"})

@spec update_tab_badge(atom(), PhoenixKit.Dashboard.Badge.t() | map() | nil) :: :ok

Updates a tab's badge.

This broadcasts an update to all subscribed LiveViews.

Examples

Registry.update_tab_badge(:notifications, Badge.count(5))
Registry.update_tab_badge(:printers, Badge.count(3, color: :warning))