# `PhiaUi.Components.Sidebar`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/navigation/sidebar.ex#L1)

Sidebar navigation component with brand area, scrollable nav, and pinned footer.

Provides three components:

- `sidebar/1` — collapsible 240 px aside with `:default`/`:dark` variants
- `sidebar_item/1` — navigation link with active highlight, icon, and badge
- `sidebar_section/1` — groups nav items under an uppercase section label

## Example

    <.sidebar variant={:default}>
      <:brand>
        <img src="/logo.svg" alt="Acme" class="h-6 w-auto" />
      </:brand>
      <:nav_items>
        <.sidebar_section label="Main Menu">
          <.sidebar_item href="/dashboard" active={@live_action == :index}>
            Dashboard
          </.sidebar_item>
        </.sidebar_section>
      </:nav_items>
      <:footer_items>
        <.sidebar_item href="/settings">Settings</.sidebar_item>
      </:footer_items>
    </.sidebar>

# `sidebar`

Responsive sidebar with brand area, scrollable nav, and pinned footer.

The sidebar is **always 240 px wide** (set on the CSS Grid column). On desktop
it is a static grid cell with `flex flex-col` and `border-r`. On mobile the
parent `shell/1` component manages its visibility as an overlay.

The layout is a vertical flex container divided into three parts:

    ┌──────────────────────────┐  ← h-14 brand area (shrink-0, border-b)
    │  brand slot              │
    ├──────────────────────────┤
    │                          │  ← flex-1, overflow-y-auto
    │  nav_items slot          │
    │                          │
    ├──────────────────────────┤  ← shrink-0, border-t
    │  footer_items slot       │
    └──────────────────────────┘

## Example

    <.sidebar variant={:default}>
      <:brand>
        <img src="/logo.svg" alt="Acme" class="h-6 w-auto" />
      </:brand>
      <:nav_items>
        <.sidebar_item href="/dashboard" active>Dashboard</.sidebar_item>
      </:nav_items>
      <:footer_items>
        <.sidebar_item href="/settings">Settings</.sidebar_item>
      </:footer_items>
    </.sidebar>

## Attributes

* `id` (`:string`) - Element ID used by `mobile_sidebar_toggle/1`'s `JS.toggle/1` call.
  Keep the default unless you render multiple shells on the same page.

  Defaults to `"sidebar-drawer"`.
* `collapsed` (`:boolean`) - When `true`, translates the sidebar off-screen via `-translate-x-full`.
  Useful for programmatic collapse without the mobile overlay pattern.

  Defaults to `false`.
* `class` (`:string`) - Additional CSS classes. Defaults to `nil`.
* `variant` (`:atom`) - Visual variant for the sidebar background.

  - `:default` — uses `--sidebar-background` and `--sidebar-foreground` tokens,
    which respect the current color theme and dark mode.
  - `:dark` — forces a dark background regardless of color mode. Applies
    `dark bg-sidebar-background text-sidebar-foreground` classes directly,
    producing the "always dark" look used by tools like Vercel or Linear.

  Defaults to `:default`. Must be one of `:default`, or `:dark`.
* Global attributes are accepted. HTML attributes forwarded to the aside element.
## Slots

* `brand` - Logo or application name area rendered at the top of the sidebar inside a
  `h-14` row that aligns with the topbar height. Typically holds a wordmark,
  icon-plus-name combo, or workspace switcher.

* `nav_items` - Primary navigation items (the main middle section of the sidebar).
  This slot is placed in an `overflow-y-auto` `<nav>` element so that
  long navigation lists scroll independently of the footer.
  Use `sidebar_section/1` and `sidebar_item/1` inside this slot.

* `footer_items` - Secondary items anchored to the bottom of the sidebar (above the fold).
  Typically holds Settings and Help links. Rendered in a `shrink-0` div
  with a top border separating it from the primary nav.

* `inner_block` - Fallback slot for fully custom sidebar content when the named slots
  (`:brand`, `:nav_items`, `:footer_items`) do not provide enough structure.
  Only rendered when `:nav_items` is empty.

# `sidebar_item`

A navigation link inside the sidebar.

Renders a full-width anchor element with:
- Active state highlighting via `bg-accent text-accent-foreground`
- Optional leading icon in its own `shrink-0` container
- Optional trailing badge count (circular pill with `bg-primary`)
- Keyboard focus outline inherited from the global focus ring tokens

## Example

    <%!-- Basic item --%>
    <.sidebar_item href="/dashboard" active={@live_action == :index}>
      Dashboard
    </.sidebar_item>

    <%!-- Item with icon and notification badge --%>
    <.sidebar_item href="/inbox" active={@live_action == :inbox} badge={@unread}>
      <:icon><.icon name="inbox" /></:icon>
      Inbox
    </.sidebar_item>

## Attributes

* `href` (`:string`) - Navigation href for the anchor element. Defaults to `"#"`.
* `active` (`:boolean`) - Highlights this item as the currently active route. Adds
  `bg-accent text-accent-foreground` when `true`. Typically derived from
  `@live_action == :route_name` in your LiveView.

  Defaults to `false`.
* `badge` (`:integer`) - Optional notification badge count displayed on the right side of the item.
  Pass `nil` (the default) to hide the badge entirely. Common for unread
  message counts, pending task counts, etc.

  Defaults to `nil`.
* `class` (`:string`) - Additional CSS classes for the anchor element. Defaults to `nil`.
* Global attributes are accepted. HTML attributes forwarded to the anchor element.
## Slots

* `icon` - Optional icon displayed before the label. Use `<.icon name="...">` inside
  this slot. The icon is wrapped in `shrink-0` so it does not compress when
  the label is long.

* `inner_block` (required) - The text label for this navigation item.

# `sidebar_item_expandable`

Collapsible sidebar section using native `<details>/<summary>`.

Uses `details-open:rotate-90` (Tailwind v4) for the animated chevron.
Zero JavaScript required — browser handles expand/collapse natively.

## Example

    <.sidebar_item_expandable label="Settings" active={@section == :settings}>
      <.sidebar_item href="/settings/profile">Profile</.sidebar_item>
      <.sidebar_item href="/settings/security">Security</.sidebar_item>
    </.sidebar_item_expandable>

## Attributes

* `label` (`:string`) (required) - Section label shown in the summary.
* `active` (`:boolean`) - When `true`, auto-opens the details element via the `open` attribute. Defaults to `false`.
* `class` (`:string`) - Additional CSS classes for the details element. Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `icon` - Optional icon displayed before the label.
* `inner_block` (required) - Nested sidebar_item/1 components.

# `sidebar_section`

Groups sidebar navigation items under an optional section label.

Use multiple `sidebar_section/1` components inside the `:nav_items` slot of
`sidebar/1` to create a visually separated, labelled hierarchy of links.

Section labels use `text-xs uppercase tracking-wider` for a compact
enterprise-style appearance. Items within the section are spaced with
`space-y-0.5` for tight, scannable lists.

## Example

    <.sidebar_section label="Analytics">
      <.sidebar_item href="/revenue" active={@live_action == :revenue}>
        Revenue
      </.sidebar_item>
      <.sidebar_item href="/retention">Retention</.sidebar_item>
    </.sidebar_section>

## Attributes

* `label` (`:string`) - Section heading displayed in small uppercase muted text above the items.
  Pass `nil` to render the items without any heading (useful for the first
  section where a heading is redundant).

  Defaults to `nil`.
* `class` (`:string`) - Additional CSS classes for the section wrapper. Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required) - sidebar_item/1 components to group under this section.

---

*Consult [api-reference.md](api-reference.md) for complete listing*