Configuration and helpers for the dashboard context selector.

The context selector allows users to switch between multiple contexts (organizations, farms, teams, workspaces, etc.) in the dashboard. Users with only one context won't see the selector.

Single Selector Configuration (Legacy)

Configure in your config/config.exs:

config :phoenix_kit, :dashboard_context_selector,
  loader: {MyApp.Farms, :list_for_user},
  display_name: fn farm -> farm.name end,
  id_field: :uuid,
  label: "Farm",
  icon: "hero-building-office",
  position: :sidebar,
  sub_position: :end,
  empty_behavior: :hide,
  session_key: "dashboard_context_uuid",
  tab_loader: {MyApp.Farms, :get_tabs_for_context}

Multiple Selectors Configuration

Configure multiple independent or dependent selectors:

config :phoenix_kit, :dashboard_context_selectors, [
  %{
    key: :organization,
    loader: {MyApp.Orgs, :list_for_user},
    display_name: fn org -> org.name end,
    label: "Organization",
    icon: "hero-building-office",
    position: :header,
    sub_position: :start,
    priority: 100
  },
  %{
    key: :project,
    depends_on: :organization,
    loader: {MyApp.Projects, :list_for_org},
    display_name: fn p -> p.name end,
    label: "Project",
    icon: "hero-folder",
    position: :header,
    sub_position: :end,
    priority: 200,
    on_parent_change: :reset
  }
]

Configuration Options

• :key - Required for multi-selector. Unique atom identifier (e.g., :organization). Used in session storage and routes.

• :loader - Required. A {Module, :function} tuple that takes a user ID and returns a list of context items. Example: {MyApp.Farms, :list_for_user} For dependent selectors, the function receives (user_uuid, parent_context).

• :display_name - Required. A function that takes a context item and returns the display string. Example: fn farm -> farm.name end

• :id_field - Optional. The field to use as the unique identifier. Defaults to :id. Can be an atom or a function.

• :label - Optional. The label shown in the UI (e.g., "Farm", "Organization"). Defaults to "Context".

• :icon - Optional. Heroicon name for the selector. Defaults to "hero-building-office".

• :position - Optional. Which area to show the selector in. Options: :header (default), :sidebar.

• :sub_position - Optional. Where within the area to place the selector. For header: :start (left, after logo), :end (right, before user menu), or {:priority, N} to sort among other header items. For sidebar: :start (top), :end (pinned to very bottom), or {:priority, N} to sort among tabs. Defaults to :start.

• :priority - Optional. Integer for ordering within same position/sub_position. Lower values come first. Defaults to 500.

• :depends_on - Optional. Key of parent selector (for dependent selectors). When set, the loader receives (user_uuid, parent_context) instead of just user_uuid.

• :on_parent_change - Optional. What to do when parent selector changes. Options: :reset (default, select first), :keep, {:redirect, "/path"}.

• :empty_behavior - Optional. What to do when user has no contexts. Options: :hide (default), :show_empty, {:redirect, "/path"}.

• :separator - Optional. Separator shown between logo and selector in header (only applies to position: :header, sub_position: :start). Defaults to "/". Set to false or nil to disable. Can be any string like "›", "|", or "·".

  Note: The separator may appear slightly off-center due to internal padding in the selector dropdown. This is a visual quirk and can be adjusted by customizing the layout template if precise alignment is required.

• :session_key - Optional. The session key for storing the selected context UUID. Defaults to "dashboard_context_uuid" for single selector, or "dashboard_context_uuids" (map) for multiple selectors.

• :tab_loader - Optional. A {Module, :function} tuple that takes a context item and returns a list of tab definitions. Enables dynamic tabs that change based on the selected context. Example: {MyApp.Farms, :get_tabs_for_context}

Usage in LiveViews

The ContextProvider on_mount hook automatically sets these assigns:

Single Selector (Legacy)

• @dashboard_contexts - List of all contexts for the user
• @current_context - The currently selected context item
• @show_context_selector - Boolean, true only if user has 2+ contexts
• @dashboard_tabs - (Optional) List of Tab structs when tab_loader is configured

Multiple Selectors

• @dashboard_contexts_map - Map of key => list of contexts
• @current_contexts_map - Map of key => current context item
• @show_context_selectors_map - Map of key => boolean
• @context_selector_configs - List of all ContextSelector configs

Access the current context in your LiveView:

def mount(_params, _session, socket) do
  context = socket.assigns.current_context
  items = MyApp.Items.list_for_context(context.id)
  {:ok, assign(socket, items: items)}
end

Or use the helper functions:

context_uuid = PhoenixKit.Dashboard.current_context_uuid(socket)