Sidebar

A composable, collapsible navigation panel wired to a Stimulus controller. Build app shells with a persistent left (or right) drawer that collapses off-canvas.

Installation

bin/rails g shadcnrb:component sidebar

Note

Because this docs page is itself rendered inside a sidebar layout, embedding a full sidebar_wrapper in the preview would create a nested layout conflict. Instead, the individual building blocks are shown below. For a full working demo, see the sidebar playground.

Usage — individual pieces

Child parts are reached via the proxy yielded by sui.sidebar_wrapper do |s|. For isolated demos outside a wrapper, sui.sidebar_proxy returns the same proxy without rendering the shell. menu_button mirrors Rails link_to — pass a name + path and the active state is auto-detected via current_page?.

<!-- default -->
<%= s.menu_button "Dashboard", "#" %>
<!-- active: true -->
<%= s.menu_button "Active item", "#", active: true %>
<!-- icon: :home -->
<%= s.menu_button "Home", "#", icon: :home %>

For anything beyond a plain link — button_to with method: :delete, Turbo options, nested icons — pass a block. The wrapper renders a styled <div role="button"> and your Rails helper fills the row.

<!-- menu_button (block form with button_to) -->
<div class="w-64 bg-sidebar rounded-md p-2">
  <%= s.menu_button do %>
    <%= button_to "Sign out", "#", method: :delete %>
  <% end %>
</div>
<!-- group_label -->
<div class="w-48 bg-sidebar rounded-md">
  <%= s.group_label "Platform" %>
</div>
<!-- separator -->
<div class="w-48 bg-sidebar rounded-md py-2">
  <%= s.separator %>
</div>

Sub-menu flyout

A collapsible group loses its menu_sub when the rail collapses to icons. s.collapsible flyout: true keeps the nested pages reachable: on the icon rail, hovering (or focusing) the menu button opens the same list as a panel to its right, headed by the button's label. Expanded, the group behaves as before. The click is inert while the flyout is on, so the inline open state survives a collapse and expand. Try it collapsed in the playground or the Nav + Sidebar block.

s.collapsible open: true, flyout: true do |c|
  s.menu_item do
    s.menu_button "Docs", collapsible: true, icon: :folder do
      c.chevron
    end
  end

  c.content do
    s.menu_sub do
      s.menu_sub_item { s.menu_sub_button "Introduction", "#" }
      s.menu_sub_item { s.menu_sub_button "Installation", "#" }
    end
  end
end

Full structure (code only)

Assemble these methods to build a complete sidebar shell. The sidebar_wrapper owns the Stimulus controller; s.trigger and s.rail both dispatch the toggle action.

sui.sidebar_wrapper do |s|
  s.sidebar do
    s.header do
      tag.span "My App", class: "font-semibold text-sm px-2"
    end
    s.content do
      s.group do
        s.group_label "Platform"
        s.group_content do
          s.menu do
            s.menu_item do
              s.menu_button "Dashboard", root_path
            end
            s.menu_item do
              s.menu_button "Settings", settings_path
            end
          end
        end
      end
      s.separator
      s.group do
        s.group_label "Account"
        s.group_content do
          s.menu do
            s.menu_item do
              s.menu_button "Profile", profile_path
            end
          end
        end
      end
    end
    s.footer do
      tag.span "Footer content"
    end
    s.rail
  end
  s.inset do
    tag.header(class: "flex items-center gap-2 p-4") do
      s.trigger
    end
    tag.div(class: "p-4") do
      tag.p "Main content area"
    end
  end
end

Persisting on the server

The cookie is the default store. To keep the choice with the user's account, pass the stored value to the helper and listen for the change event — see State persistence.

API