Sidebar

A composable, collapsible, responsive sidebar for application layouts.

See the sidebar in a complete layout

The sidebar-01 block shows collapsing, the Cmd/Ctrl+B shortcut, and the mobile drawer.

Installation

Shadwire follows shadcn/ui's open code model: the component's source is copied into your application and becomes yours. Install it with the CLI:

shadwire add sidebar --yes

The sidebar registry item installs these files:

app/components/ui_component.rb
app/components/ui/sidebar_component.rb
app/components/ui/sidebar/provider_component.rb
app/components/ui/sidebar/trigger_component.rb
app/components/ui/sidebar/rail_component.rb
app/components/ui/sidebar/inset_component.rb
app/components/ui/sidebar/input_component.rb
app/components/ui/sidebar/header_component.rb
app/components/ui/sidebar/footer_component.rb
app/components/ui/sidebar/separator_component.rb
app/components/ui/sidebar/content_component.rb
app/components/ui/sidebar/group_component.rb
app/components/ui/sidebar/group_label_component.rb
app/components/ui/sidebar/group_action_component.rb
app/components/ui/sidebar/group_content_component.rb
app/components/ui/sidebar/menu_component.rb
app/components/ui/sidebar/menu_item_component.rb
app/components/ui/sidebar/menu_button_component.rb
app/components/ui/sidebar/menu_action_component.rb
app/components/ui/sidebar/menu_badge_component.rb
app/components/ui/sidebar/menu_skeleton_component.rb
app/components/ui/sidebar/menu_sub_component.rb
app/components/ui/sidebar/menu_sub_item_component.rb
app/components/ui/sidebar/menu_sub_button_component.rb
app/helpers/ui/sidebar_helper.rb
app/javascript/controllers/ui_sidebar_controller.js
vendor/shadwire/shadwire.css

This component uses Stimulus, so the application needs importmap-rails and stimulus-rails with automatic controller loading.

Haven't installed the CLI yet? gem install shadwire, then shadwire init.

Usage

Wrap the page in ui_sidebar_provider; it hosts the controller and exposes the widths as CSS variables.

<%= ui_sidebar_provider do %>
  <%= ui_sidebar do %>
    <%= ui_sidebar_content do %>
      <%= ui_sidebar_group do %>
        <%= ui_sidebar_group_label { "Application" } %>
        <%= ui_sidebar_group_content do %>
          <%= ui_sidebar_menu do %>
            <%= ui_sidebar_menu_item do %>

<%= ui_sidebar_provider do %>
  <%= ui_sidebar do %>
    <%= ui_sidebar_content do %>
      <%= ui_sidebar_group do %>
        <%= ui_sidebar_group_label { "Application" } %>
        <%= ui_sidebar_group_content do %>
          <%= ui_sidebar_menu do %>
            <%= ui_sidebar_menu_item do %>
              <%= ui_sidebar_menu_button(tag: :a, href: "#", is_active: true) { "Home" } %>
            <% end %>
          <% end %>
        <% end %>
      <% end %>
    <% end %>
    <%= ui_sidebar_rail %>
  <% end %>
  <%= ui_sidebar_inset do %>
    <%= ui_sidebar_trigger %>
  <% end %>
<% end %>

Or render the components directly:

<%= render Ui::Sidebar::ProviderComponent.new do %>
  <%= render Ui::SidebarComponent.new(collapsible: :icon) do %>
    <%= render Ui::Sidebar::ContentComponent.new do %>
      <%= render Ui::Sidebar::MenuComponent.new do %>
        <%= render Ui::Sidebar::MenuItemComponent.new do %>
          <%= render Ui::Sidebar::MenuButtonComponent.new(tooltip: "Home") { "Home" } %>
        <% end %>
      <% end %>

<%= render Ui::Sidebar::ProviderComponent.new do %>
  <%= render Ui::SidebarComponent.new(collapsible: :icon) do %>
    <%= render Ui::Sidebar::ContentComponent.new do %>
      <%= render Ui::Sidebar::MenuComponent.new do %>
        <%= render Ui::Sidebar::MenuItemComponent.new do %>
          <%= render Ui::Sidebar::MenuButtonComponent.new(tooltip: "Home") { "Home" } %>
        <% end %>
      <% end %>
    <% end %>
  <% end %>
  <%= render Ui::Sidebar::InsetComponent.new do %>
    <%= render Ui::Sidebar::TriggerComponent.new %>
  <% end %>
<% end %>

Composition

Sidebar::Provider (data-controller="ui-sidebar"; sets the widths as CSS vars)
|-- Sidebar (peer/group; data-state/collapsible/side/variant/mobile)
|   |-- Sidebar::Header  (e.g. a switcher + Sidebar::Input)
|   |-- Sidebar::Content
|   |   `-- Sidebar::Group > Sidebar::GroupLabel + Sidebar::GroupContent
|   |       `-- Sidebar::Menu > Sidebar::MenuItem
|   |           > Sidebar::MenuButton (+ MenuAction / MenuBadge / MenuSub)
|   |-- Sidebar::Footer

Sidebar::Provider (data-controller="ui-sidebar"; sets the widths as CSS vars)
|-- Sidebar (peer/group; data-state/collapsible/side/variant/mobile)
|   |-- Sidebar::Header  (e.g. a switcher + Sidebar::Input)
|   |-- Sidebar::Content
|   |   `-- Sidebar::Group > Sidebar::GroupLabel + Sidebar::GroupContent
|   |       `-- Sidebar::Menu > Sidebar::MenuItem
|   |           > Sidebar::MenuButton (+ MenuAction / MenuBadge / MenuSub)
|   |-- Sidebar::Footer
|   `-- Sidebar::Rail
`-- Sidebar::Inset (Sidebar::Trigger opens/closes; Cmd/Ctrl+B toggles)

Examples

Preview

A contained sidebar (collapsible: :none) with a header, groups and a menu. The full block, with collapsing and a mobile drawer, is at /blocks/sidebar-01.

Acme Inc

Application

Content

<div class="flex h-80 w-full max-w-md overflow-hidden rounded-lg border bg-card text-left"
     style="--sidebar-width: 14rem; --sidebar-width-icon: 3rem; --sidebar-width-mobile: 14rem;">
  <%= ui_sidebar(collapsible: :none, class: "border-r") do %>
    <%= ui_sidebar_header do %>
      <div class="px-2 py-1.5 text-sm font-semibold">Acme Inc</div>
    <% end %>
    <%= ui_sidebar_content do %>
      <%= ui_sidebar_group do %>

<div class="flex h-80 w-full max-w-md overflow-hidden rounded-lg border bg-card text-left"
     style="--sidebar-width: 14rem; --sidebar-width-icon: 3rem; --sidebar-width-mobile: 14rem;">
  <%= ui_sidebar(collapsible: :none, class: "border-r") do %>
    <%= ui_sidebar_header do %>
      <div class="px-2 py-1.5 text-sm font-semibold">Acme Inc</div>
    <% end %>
    <%= ui_sidebar_content do %>
      <%= ui_sidebar_group do %>
        <%= ui_sidebar_group_label { "Application" } %>
        <%= ui_sidebar_group_content do %>
          <%= ui_sidebar_menu do %>
            <% [ [ "Inbox", "inbox", true ], [ "Projects", "folder", false ], [ "Team", "users", false ] ].each do |label, icon, active| %>
              <%= ui_sidebar_menu_item do %>
                <%= ui_sidebar_menu_button(tag: :a, href: "#", is_active: active) do %>
                  <%= ui_icon(icon) %>
                  <span><%= label %></span>
                <% end %>
              <% end %>
            <% end %>
          <% end %>
        <% end %>
      <% end %>
    <% end %>
  <% end %>
  <main class="flex flex-1 items-center justify-center p-4 text-sm text-muted-foreground">
    Content
  </main>
</div>

API reference

API	Element	Description
`ui_sidebar_provider`	`div`	Hosts the `ui-sidebar` controller; accepts `default_open:` and `cookie_name:`.
`ui_sidebar`	`div`	The panel. Accepts `side:` (`:left`/`:right`), `variant:` (`:sidebar`/`:floating`/`:inset`) and `collapsible:` (`:offcanvas`/`:icon`/`:none`).
`ui_sidebar_trigger`	`button`	Toggles the sidebar (click or Cmd/Ctrl+B).
`ui_sidebar_rail`	`button`	The strip along the inner edge that toggles collapsing.
`ui_sidebar_inset`	`main`	The content area beside the sidebar.
`ui_sidebar_header` / `ui_sidebar_footer`	`div`	The top and bottom regions.
`ui_sidebar_content`	`div`	The scrollable region holding the groups.
`ui_sidebar_group` / `_group_label` / `_group_content`	`div`	A labelled menu section. The label takes `tag:`.
`ui_sidebar_group_action`	`button`	An action pinned to the group's label; `tag:`.
`ui_sidebar_menu` / `_menu_item`	`ul` / `li`	The list of menu items.
`ui_sidebar_menu_button`	`button`/`a`	`is_active:`, `variant:`, `size:`, `tag:` and `tooltip:` (visible in icon mode only).
`ui_sidebar_menu_action` / `_menu_badge`	`button` / `div`	An action and a badge pinned to the right of the item. The action takes `tag:`, and `show_on_hover:` to show it only while the row is hovered or focused.
`ui_sidebar_menu_sub` / `_menu_sub_item` / `_menu_sub_button`	`ul` / `li` / `a`	A nested submenu. The button takes `is_active:`, `size:` and `tag:`.
`ui_sidebar_menu_skeleton`	`div`	A loading placeholder; `show_icon:`.