LedgerUI.Components.Sidebar (LedgerUI v0.2.0)

Copy Markdown View Source

The side menu of the shell, in four formats that read the same data:

  • sections (default): the brand with a company switcher, groups with an uppercase mono label, "settings and help" at the foot and the plan card.

  • rail: a 64px rail of icons (logo, home, one icon per group, extra apps in coloured circles, the foot items) beside the panel of the active module (title, create button, items, "try" shortcuts, trial card).

  • tree: the brand with a collapse button, collapsible groups, children joined by a line, square coloured icons and the user card at the foot.

  • nested: the shadcn/ui sidebar: team switcher, quiet group labels, items with children and the user at the foot, both able to open a menu.

    <.sidebar format="rail" nav={MyAppWeb.Nav.items(assigns)} current={@current_path}
      brand={%{name: "Ledger", logo: "S"}} user={%{name: "Marina Costa", email: "marina@ledger.com"}} />

Changing format changes how the menu is drawn, never the items.

variant

"floating" (default) is the card with corners and a shadow, "sidebar" sits flush with a line at its edge, "inset" drops the card too.

The menu data

nav is a list of maps, in order. A map with group is a group, any other is an item.

Item keys: label, icon (a short name of the table in the README, or any icon name), navigate / patch / href, count, badge, color, children, collapsible, open, active, kbd (a shortcut at the right), caret ("down" | "right": a chevron at the end without children), loose (drawn outside the column of the items around it), current, match ("exact" | "prefix"), disabled (a "coming soon" item: a span with aria-disabled="true"), title, formats and style.

Group keys: group, icon, items, collapsible, open, navigate / patch / href, footer: true (the foot of the menu), action (%{label, navigate, icon}) and try (%{label, items}) for the rail panel.

Configuration

config :ledger_ui, :shell, sidebar: :sections, nav: {MyAppWeb.Nav, :items}, footer: :version, version: "v1.4.2"

What you pass always wins.

The foot

footer: "user" (the user card / the avatar of the rail), "version" (the version line: a status dot, v1.4.2, the build and a "What's new" link; version is a string or %{version, build, navigate, label, title, status}), "none", or left out (each format's own).

Collapsing

Every format collapses to icons (tooltips with the label, counts turn into dots) with the LedgerUI.Sidebar hook: collapsed is the start, on_collapse is pushed with %{"id" => id, "collapsed" => boolean}, the choice is kept in localStorage["ledger-rail"] (persist), rail_toggle/1 collapses it from anywhere and so does Ctrl/Cmd + shortcut. Below 768px the menu is a top bar with a hamburger.

Summary

Functions

sidebar(assigns)

Attributes

  • id (:string) - Defaults to "sidebar".
  • format (:any) - Defaults to nil.
  • nav (:list) - Defaults to nil.
  • current (:any) - The current path, matched against the items' links; or, with <:item> slots, an item's name. Defaults to nil.
  • brand (:map) - Defaults to nil.
  • workspace (:map) - The workspace the menu belongs to, %{name:, context:}: a brand (the chart mark, the name and the muted context line) when brand is not given. Defaults to nil.
  • views_label (:string) - The caption of the group of the <:view> items. Defaults to "Views".
  • user (:map) - Defaults to nil.
  • footer (:any) - Defaults to nil.
  • show_user (:boolean) - Defaults to nil.
  • version (:any) - Defaults to nil.
  • plan (:map) - Defaults to nil.
  • trial (:map) - Defaults to nil.
  • rail_extra (:list) - Defaults to [].
  • collapsible (:boolean) - Defaults to true.
  • match (:string) - Defaults to "exact". Must be one of "exact", or "prefix".
  • persist_groups (:boolean) - Defaults to false.
  • collapsed (:boolean) - Defaults to false.
  • persist (:boolean) - Defaults to true.
  • on_collapse (:string) - Defaults to nil.
  • target (:any) - Defaults to nil.
  • shortcut (:string) - Defaults to "b".
  • variant (:string) - Defaults to "floating". Must be one of "floating", "sidebar", or "inset".
  • label (:any) - Defaults to "Main menu".
  • collapse_label (:string) - Defaults to "Collapse menu".
  • mobile_label (:string) - Defaults to "Menu".
  • nav_class (:any) - Classes of the column that holds the items (lu-hl-nav animates them). Defaults to nil.
  • flat (:boolean) - Draws the items straight in the menu, without the column that wraps a run of them. Defaults to false.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted.

Slots

  • item - A link of the menu, its content the label, instead of nav (the same keys as an item of nav). Accepts attributes:
    • icon (:string)
    • name (:any) - Marks the item active when current is this name.
    • navigate (:string)
    • patch (:string)
    • href (:string)
    • badge (:any)
    • count (:any)
    • tone (:string) - neg, pos, warn, info: the colour of the badge.
    • active (:boolean)
    • label (:string) - The text, also the tooltip and the accessible name of the collapsed and rail menus; the content when not given.
  • view - A saved view: an item of the group views_label after the <:item>s. Accepts attributes:
    • icon (:string)
    • name (:any)
    • navigate (:string)
    • patch (:string)
    • href (:string)
    • count (:any)
    • label (:string)
  • brand_mark - Replaces the logo and the name of the brand.
  • mobile_drawer - Content of the menu body shown only below 768px.
  • sidebar_footer - At the end of the foot of the menu.