Skip to content

Layout

Use layout to build a main/sidebar layout.
  • Alpha
  • Not reviewed for accessibility

Layout provides foundational patterns for responsive pages. Layout can be used for simple two-column pages, or it can be nested to provide flexible 3-column experiences. On smaller screens, Layout uses vertically stacked rows to display content.

Layout flows as both column, when there's enough horizontal space to render both Main and Sidebarside-by-side (on a desktop of tablet device, per instance); or it flows as a row, when Main and Sidebar are stacked vertically (e.g. on a mobile device). Layout should always work in any screen size.

Accessibility

Keyboard navigation follows the markup order. Decide carefully how the focus order should be be by deciding whether main or sidebar comes first in code. The code order won’t affect the visual position.

Arguments

NameTypeDefaultDescription
stacking_breakpointSymbol:mdWhen the Layout should change from rows into columns. One of :lg, :md, or :sm.
first_in_sourceSymbol:sidebarWhich element to render first in the HTML. This will change the keyboard navigation order. One of :main or :sidebar.
gutterSymbol:defaultThe amount of space between the main section and the sidebar. One of :condensed, :default, :none, or :spacious.
system_argumentsHashN/ASystem arguments

Slots

main

The layout's main content.

NameTypeDefaultDescription
widthSymbolN/AOne of :full, :lg, :md, or :xl.
system_argumentsHashN/ASystem arguments

The layout's sidebar.

NameTypeDefaultDescription
widthSymbolN/AOne of :default, :narrow, or :wide.
col_placementSymbolN/ASidebar placement when Layout is in column modes. One of :end or :start.
row_placementSymbolN/ASidebar placement when Layout is in row mode. One of :end, :none, or :start.
system_argumentsHashN/ASystem arguments

Examples

Default

Sidebar
Main
<%= render(Primer::Alpha::Layout.new) do |c| %>
<% c.with_main(border: true) { "Main" } %>
<% c.with_sidebar(border: true) { "Sidebar" } %>
<% end %>

Main widths

When full, the main column will stretch to cover all the available width. Otherwise, the main column will try to be centered in the screen; it may appear aligned to the left when there isn't enough space. Use smaller maximum widths in the main column to facilitate interface scanning and reading. When flowing as a row, Main takes the full width.

Sidebar
Main
Sidebar
Main
Sidebar
Main
Sidebar
Main
<%= render(Primer::Alpha::Layout.new) do |c| %>
<% c.with_main(width: :full, border: true) { "Main" } %>
<% c.with_sidebar(border: true) { "Sidebar" } %>
<% end %>
<%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
<% c.with_main(width: :md, border: true) { "Main" } %>
<% c.with_sidebar(border: true) { "Sidebar" } %>
<% end %>
<%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
<% c.with_main(width: :lg, border: true) { "Main" } %>
<% c.with_sidebar(border: true) { "Sidebar" } %>
<% end %>
<%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
<% c.with_main(width: :xl, border: true) { "Main" } %>
<% c.with_sidebar(border: true) { "Sidebar" } %>
<% end %>

Sets the sidebar width. The width is predetermined according to the breakpoint instead of it being percentage-based. - default: [md: 256px, lg: 296px, xl: 320px] - narrow: [md: 240px, lg: 256px, xl: 296px] - wide: [md: 296px, lg: 320px, xl: 344px] When flowing as a row, Sidebar takes the full width.

Sidebar
Main
Sidebar
Main
Sidebar
Main
<%= render(Primer::Alpha::Layout.new) do |c| %>
<% c.with_main(border: true) { "Main" } %>
<% c.with_sidebar(width: :default, border: true) { "Sidebar" } %>
<% end %>
<%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
<% c.with_main(border: true) { "Main" } %>
<% c.with_sidebar(width: :narrow, border: true) { "Sidebar" } %>
<% end %>
<%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
<% c.with_main(border: true) { "Main" } %>
<% c.with_sidebar(width: :wide, border: true) { "Sidebar" } %>
<% end %>

Use start for sidebars that manipulate local navigation, while right-aligned end is useful for metadata and other auxiliary information.

Sidebar
Main
Sidebar
Main
<%= render(Primer::Alpha::Layout.new) do |c| %>
<% c.with_main(border: true) { "Main" } %>
<% c.with_sidebar(col_placement: :start, border: true) { "Sidebar" } %>
<% end %>
<%= render(Primer::Alpha::Layout.new( mt: 5)) do |c| %>
<% c.with_main(border: true) { "Main" } %>
<% c.with_sidebar(col_placement: :end, border: true) { "Sidebar" } %>
<% end %>

When flowing as a row, whether the sidebar is rendered first or last in the layout, or, if it's entirely hidden from the user. When hidden, make sure the experience is not degraded on smaller screens, and the user can still access the sidebar content somehow. For instance, the user may not see a Settings navigation sidebar when drilled down on a page, but they can still navigate to the Settings landing page to interact with the local navigation.

Sidebar
Main
Sidebar
Main
Sidebar
Main
<%= render(Primer::Alpha::Layout.new) do |c| %>
<% c.with_main(border: true) { "Main" } %>
<% c.with_sidebar(row_placement: :start, border: true) { "Sidebar" } %>
<% end %>