@spec clear_attention(atom()) :: :ok

Clears attention animation from a tab.

@spec clear_badge(atom()) :: :ok

Clears a tab's badge.

@spec context_selector_enabled?() :: boolean()

Checks if the context selector feature is enabled.

Examples

if PhoenixKit.Dashboard.context_selector_enabled?() do
  # Context switching is available
end

@spec count_badge(
  integer(),
  keyword()
) :: PhoenixKit.Dashboard.Badge.t()

Creates a count badge.

@spec current_context(Phoenix.LiveView.Socket.t() | map()) :: any() | nil

Gets the current context from socket assigns.

Returns nil if context selector is not configured or no context is selected.

Examples

context = PhoenixKit.Dashboard.current_context(socket)
# => %MyApp.Farm{id: 1, name: "My Farm"}

context = PhoenixKit.Dashboard.current_context(socket.assigns)
# => %MyApp.Farm{id: 1, name: "My Farm"}

@spec current_context_id(Phoenix.LiveView.Socket.t() | map()) :: any() | nil

Gets the current context ID from socket assigns.

Convenience function that extracts just the ID.

Examples

context_id = PhoenixKit.Dashboard.current_context_id(socket)
# => 1

@spec decrement_badge(atom(), integer()) :: :ok

Decrements a tab's count badge by a given amount.

Will not go below 0.

@spec divider(keyword()) :: PhoenixKit.Dashboard.Tab.t()

Creates a divider for visual separation in the sidebar.

Examples

PhoenixKit.Dashboard.divider(priority: 150)
PhoenixKit.Dashboard.divider(priority: 200, label: "Account")

@spec dot_badge(keyword()) :: PhoenixKit.Dashboard.Badge.t()

Creates a dot badge.

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

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

Options

• :scope - The current authentication scope for permission filtering

Examples

tabs = PhoenixKit.Dashboard.get_admin_tabs(scope: scope)

@spec get_all_viewer_counts() :: map()

Gets viewer counts for all tabs.

Examples

counts = PhoenixKit.Dashboard.get_all_viewer_counts()
# => %{orders: 3, settings: 1, printers: 2}

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

Gets all registered tab groups.

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

Gets all subtabs for a given parent tab ID.

Examples

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

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

Gets a specific tab by ID.

Examples

tab = PhoenixKit.Dashboard.get_tab(:orders)

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

Gets all registered tabs, sorted by priority.

Options

• :scope - Filter by visibility using the current scope
• :include_hidden - Include tabs that would be hidden (default: false)

Examples

tabs = PhoenixKit.Dashboard.get_tabs()
tabs = PhoenixKit.Dashboard.get_tabs(scope: socket.assigns.phoenix_kit_current_scope)

@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.

Examples

tabs = PhoenixKit.Dashboard.get_tabs_with_active("/dashboard/orders")

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

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

Examples

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

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

Gets all user-level tabs, filtered by visibility and scope.

Options

• :scope - The current authentication scope for visibility filtering

Examples

tabs = PhoenixKit.Dashboard.get_user_tabs(scope: scope)

@spec get_viewer_count(atom()) :: integer()

Gets the number of users viewing a specific tab.

Examples

count = PhoenixKit.Dashboard.get_viewer_count(:orders)

@spec group_header(keyword()) :: PhoenixKit.Dashboard.Tab.t()

Creates a group header for organizing tabs.

Examples

PhoenixKit.Dashboard.group_header(id: :farm, label: "Farm Management", priority: 200)

@spec has_multiple_contexts?(Phoenix.LiveView.Socket.t() | map()) :: boolean()

Checks if the user has multiple contexts available.

Returns true only if context selector is enabled and user has 2+ contexts.

Examples

if PhoenixKit.Dashboard.has_multiple_contexts?(socket) do
  # Show context-specific UI
end

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

Checks if a tab has any subtabs.

Examples

PhoenixKit.Dashboard.has_subtabs?(:orders)
# => true

@spec increment_badge(atom(), integer()) :: :ok

Increments a tab's count badge by a given amount.

Examples

PhoenixKit.Dashboard.increment_badge(:notifications)
PhoenixKit.Dashboard.increment_badge(:notifications, 5)

@spec live_badge(String.t(), atom() | (map() -> any()), keyword()) ::
  PhoenixKit.Dashboard.Badge.t()

Creates a live badge that subscribes to PubSub updates.

@spec load_admin_defaults() :: :ok

Loads the default admin tabs into the registry.

Called automatically on Registry startup, but can be called manually to reload defaults after changes.

@spec matches_path?(PhoenixKit.Dashboard.Tab.t(), String.t()) :: boolean()

Checks if a tab matches the given path.

@spec new_badge(map() | keyword()) ::
  {:ok, PhoenixKit.Dashboard.Badge.t()} | {:error, String.t()}

Creates a new Badge struct.

See PhoenixKit.Dashboard.Badge.new/1 for options.

@spec new_tab(map() | keyword()) ::
  {:ok, PhoenixKit.Dashboard.Tab.t()} | {:error, String.t()}

Creates a new Tab struct.

See PhoenixKit.Dashboard.Tab.new/1 for options.

@spec new_tab!(map() | keyword()) :: PhoenixKit.Dashboard.Tab.t()

Creates a new Tab struct, raising on error.

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

Gets the PubSub topic for tab updates.

Subscribe to this topic to receive real-time tab updates in LiveViews.

Example

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

def handle_info({:tab_updated, tab}, socket) do
  # Handle tab update - refresh sidebar
  {:noreply, assign(socket, tabs: PhoenixKit.Dashboard.get_tabs())}
end

def handle_info(:tabs_refreshed, socket) do
  # Full tab list refresh
  {:noreply, assign(socket, tabs: PhoenixKit.Dashboard.get_tabs())}
end

@spec register_admin_tabs(atom(), [map() | PhoenixKit.Dashboard.Tab.t()]) ::
  :ok | {:error, term()}

Registers admin tabs for an application namespace.

Automatically sets level: :admin on all tabs.

Examples

PhoenixKit.Dashboard.register_admin_tabs(:my_app, [
  %{id: :admin_analytics, label: "Analytics", path: "/admin/analytics",
    icon: "hero-chart-bar", permission: "dashboard"}
])

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

Registers tab groups for organizing the sidebar.

Examples

PhoenixKit.Dashboard.register_groups([
  %{id: :main, label: nil, priority: 100},
  %{id: :farm, label: "Farm Management", priority: 200, icon: "hero-cube"},
  %{id: :account, label: "Account", priority: 900}
])

@spec register_tabs(atom(), [map() | PhoenixKit.Dashboard.Tab.t()]) ::
  :ok | {:error, term()}

Registers dashboard tabs for an application namespace.

Examples

# Register multiple tabs
PhoenixKit.Dashboard.register_tabs(:my_app, [
  %{id: :orders, label: "Orders", path: "/dashboard/orders", icon: "hero-shopping-bag"},
  %{id: :history, label: "History", path: "/dashboard/history", icon: "hero-clock"}
])

# Register a single tab
PhoenixKit.Dashboard.register_tabs(:my_app, [
  Tab.new!(id: :custom, label: "Custom", path: "/dashboard/custom")
])

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

Sets an attention animation on a tab.

Animation Types

• :pulse - Gentle pulsing glow
• :bounce - Bouncing motion
• :shake - Shaking motion (for errors/alerts)
• :glow - Glowing effect

Examples

PhoenixKit.Dashboard.set_attention(:alerts, :pulse)
PhoenixKit.Dashboard.set_attention(:errors, :shake)

@spec show_subtabs?(PhoenixKit.Dashboard.Tab.t(), boolean()) :: boolean()

Checks if subtabs should be shown for a tab based on its display setting and active state.

Examples

PhoenixKit.Dashboard.show_subtabs?(tab, true)  # parent is active
# => true (for :when_active or :always)

PhoenixKit.Dashboard.show_subtabs?(tab, false)  # parent not active
# => true (only for :always)

@spec status_badge(
  atom() | String.t(),
  keyword()
) :: PhoenixKit.Dashboard.Badge.t()

Creates a status badge.

@spec subscribe() :: :ok | {:error, term()}

Subscribes the current process to tab updates.

Convenience wrapper around Phoenix.PubSub.subscribe/2.

@spec subtab?(PhoenixKit.Dashboard.Tab.t()) :: boolean()

Checks if a tab is a subtab (has a parent).

Examples

PhoenixKit.Dashboard.subtab?(:pending_orders)
# => true

@spec track_presence(Phoenix.LiveView.Socket.t(), atom(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Tracks a user's presence on a dashboard tab.

Examples

PhoenixKit.Dashboard.track_presence(socket, :orders)

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

Unregisters a specific tab by ID.

Examples

PhoenixKit.Dashboard.unregister_tab(:orders)

@spec unregister_tabs(atom()) :: :ok

Unregisters all tabs for a namespace.

Examples

PhoenixKit.Dashboard.unregister_tabs(:my_app)

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

Updates a tab's badge.

Examples

# Set a count badge
PhoenixKit.Dashboard.update_badge(:notifications, 5)

# Set badge with options
PhoenixKit.Dashboard.update_badge(:alerts, count: 3, color: :error, pulse: true)

# Set a dot badge
PhoenixKit.Dashboard.update_badge(:status, type: :dot, color: :success)

# Clear a badge
PhoenixKit.Dashboard.update_badge(:notifications, nil)

@spec update_tab(atom(), map()) :: :ok | {:error, :not_found}

Updates an existing tab's attributes by ID.

Examples

PhoenixKit.Dashboard.update_tab(:admin_dashboard, %{label: "Home", icon: "hero-home"})

@spec visible?(PhoenixKit.Dashboard.Tab.t(), map()) :: boolean()

Checks if a tab is visible for the given scope.