Layout component documentation status
The Layout component guidelines are in progress and not yet complete.
layout
80 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Layout component Rails identifiers
The Layout component has two Rails identifiers: Primer::Alpha::Layout and Primer::LayoutComponent.
Layout component purpose
Layout provides foundational patterns for responsive pages.
Stack component status
Stack is marked as an experimental component.
Stack interface guidelines not yet available
Stack interface guidelines are coming soon and are not yet available in the current documentation.
Stack component purpose and responsiveness
Stack is a layout component that creates responsive horizontal and vertical flows. It is currently in experimental status.
Inline-block grid alternative
Column widths can be used with d-inline-block as an alternative to floated grids. Column widths and other utilities can be used on elements such as lists to create layouts while keeping markup semantically correct.
Display table grids
Display table utilities can be used with columns to provide alternative layout options. A useful example is keeping the height of the container equal across a row when the length of content may differ. Table cells will fill the width of their container even when the total columns doesn't add up to 12.
Container max-widths and sizing
Container widths match the breakpoints and are available at sm, md, lg, and xl sizes. Containers apply a max-width rather than a fixed width for responsive layouts, and they center the container.
Grid structure: 12 columns, percentage-based
The grid is 12 columns and percentage-based. The number of columns a container spans can be adjusted across breakpoints for responsive layouts.
Flexbox grid usage
Flexbox grids can be created by using flex utilities on the container and columns. This approach is useful for keeping columns the same height, justifying content, vertically aligning items, and working with responsive layouts.
Reversing float grid column order
To reverse the order of columns in a float grid, use float-right to float columns to the right.
Float-based grid with clearfix
Use .clearfix on the container and float utilities with columns to create a floated grid layout.
Grid nesting capability
Grid layouts can be infinitely nested within other columns since column widths are percentage-based. Nesting should be used sensibly and not taken to excessive depths.
Centering columns with mx-auto
Use .mx-auto to center columns within a container.
Column width usage
Column widths can be used with any other block or inline-block elements to add percentage-based widths.
Column offset classes
Column offset classes can push a div over X number of columns. They work responsively using responsive breakpoint modifiers.
Gutter options and responsive support
Gutters can be created using gutter styles or padding utilities. There are three gutter style options: default gutter, gutter-condensed, and gutter-spacious. Gutter styles support responsive breakpoint modifiers. Gutter styles add padding to the left and right side of each column and apply a negative margin to the container to ensure content inside each column lines up with content outside of the grid.
Width utility .width-fit
Use .width-fit to set max-width to 100%.
Width utility .width-full
Use .width-full to set width to 100%.
Width utility .width-auto
Use .width-auto to reset width to auto (initial value). Typically used with responsive variants.
Height utility .height-fit
Use .height-fit to set max-height to 100%.
Height utility .height-full
Use .height-full to set height to 100%.
Position utilities available
Position utilities can be used to alter the default document flow. Use .top-0, .right-0, .bottom-0, and .left-0 to further specify an element's final position. Be careful when using positioning, as it is often unnecessary and commonly misused.
Relative positioning utility
Use .position-relative to create a new stacking context. Other elements are displayed as if the positioned element were in its normal position and taking up space.
Absolute positioning utility
Use .position-absolute to take elements out of the normal document flow.
Fixed positioning utility
Use .position-fixed to position an element relative to the viewport. Be careful when using fixed positioning as it is tricky to use and can lead to unwanted side effects.
Fixed positioning to fill entire width or height
Use opposing directions (top-0 and bottom-0 for height, left-0 and right-0 for width) with .position-fixed to fill an entire width or height.
Sticky positioning utility
Use .position-sticky to keep an element stuck to an edge as long as its parent is visible. Using the .position-sticky class by itself doesn't have any effect; an additional [top|bottom|left|right]-0 class is required.
Sticky positioning best practices
When using sticky positioning: add a background color to sticky elements so it covers the content underneath, and use style="z-index: 1;" (or higher) in case there are other elements with z-index.
Sticky positioning at top
Combine .position-sticky with .top-0 to keep an element stuck to the top.
Sticky positioning at bottom
Combine .position-sticky with .bottom-0 to keep an element stuck to the bottom. Can be used as a footer or toolbar.
Sticky positioning left and right
Combine .position-sticky with .left-0 or .right-0 to keep elements stuck to the left or right when scrolling horizontally.
Screen reader only utility
Use .sr-only to position an element outside of the viewport for screen reader access only. Even though the element cannot be seen, make sure it still has a sensible tab order.
Show on focus utility
Use .show-on-focus to visually hide an element and only show it when focused. This utility can be used to provide additional functionality for keyboard users.
Media object creation
Create a media object with utilities. A media object consists of a fixed-width or flexible media component (like an icon or image) alongside flexible content.
Double-sided media object
Create a double-sided media object for a container with a flexible center. This layout has media on both sides with flexible content in the middle.
Media object with flexbox
A media object can also be created with flexbox utilities instead of floats, which can be useful for changing the vertical alignment.
Responsive position utilities
Position utilities can be applied or changed per breakpoint in responsive layouts. Each responsive position utility is applied to the specified breakpoint and up, using the formula position-[breakpoint]-[property], for example position-md-absolute.
Display utilities available
The following display utilities are available: .d-block, .d-none, .d-inline, .d-inline-block, .d-table, and .d-table-cell.
Hidden attribute behavior
As of Primer v10.10.0, the primer-base includes a rule that sets display: none !important for any element with the HTML hidden attribute. Use the hidden attribute (and corresponding JavaScript property) if you are going to programmatically show and hide content.
How to toggle element visibility in JavaScript
Rather than toggling the d-none class in JavaScript, toggle the hidden property on an element. This approach avoids having to restore any more specific display utility (d-inline or d-flex, for instance) due to stylesheet ordering. Use element.hidden = !visible instead of element.classList.toggle().
When to use hidden attribute vs d-none utility
Use the hidden attribute for programmatically showing and hiding content. Use d-none and its responsive variants (d-sm-block, d-lg-none) to conditionally show content at different screen sizes.
Display table wrapping issues
There are known issues with using display:table and wrapping long strings, particularly in Firefox. You may need to use table-fixed on elements with d-table and apply column widths to table cells using column width styles.
Responsive display utilities available
.d-block, .d-none, .d-inline, and .d-inline-block are available as responsive utilities using the formula d-[breakpoint]-[property], for example d-md-inline-block. Each responsive display utility is applied to the specified breakpoint and up.
Responsive hide utilities available
Hide utilities can be applied per breakpoint using the formula hide-[breakpoint], for example hide-sm. Hide utilities act differently from other responsive styles and are applied to each breakpoint-range only.
Responsive hide breakpoint ranges
The responsive hide utilities and their ranges are: -sm (0–543px), -md (544px–767px), -lg (768px–1011px), -xl (1012px and above).
Text direction utilities
.direction-ltr or .direction-rtl can be used to change the text direction. This is especially helpful when paired with .d-table, .d-table-cell, and .v-align-middle to create equal height, vertically centered, alternating content.
Visibility utilities available
Use .v-hidden and .v-visible to adjust the visibility of an element.
Overflow utilities available
General overflow utilities: .overflow-hidden, .overflow-scroll, .overflow-auto, and .overflow-visible. Axis-specific utilities: .overflow-x-auto, .overflow-x-hidden, .overflow-x-scroll, .overflow-x-visible, .overflow-y-auto, .overflow-y-hidden, .overflow-y-scroll, .overflow-y-visible.
Overflow utility for block formatting context
.overflow-hidden can be used to create a new block formatting context or clear floats.
Responsive overflow utilities
Overflow utilities can be applied or changed per breakpoint. Each responsive overflow utility is applied to the specified breakpoint and up, using the formula overflow-[breakpoint]-[axis]-[property], for example overflow-md-x-visible.
Float utilities available
Use .float-left and .float-right to set floats, and .clearfix to clear. Using floats are discouraged since flexbox offers more features and doesn't need to be cleared.
Responsive float utilities
Float utilities can be applied or changed per breakpoint using the formula float-[breakpoint]-[property], for example float-md-left. Each responsive float utility is applied to the specified breakpoint and up. Remember to use .clearfix to clear.
Vertical alignment utilities available
Use .v-align-baseline, .v-align-top, .v-align-middle, or .v-align-bottom to adjust the alignment of an element. The vertical-align property only applies to inline or table-cell boxes.
Text alignment utilities available
Use v-align-text-top or v-align-text-bottom to adjust the alignment of an element with the top or bottom of the parent element's font.
Viewport ranges definition
Primer defines three viewport ranges for responsive layouts based on viewport width: narrow (< 768px, 1 column), regular (>= 768px, up to 2 columns), and wide (>= 1400px, up to 3 columns). Viewport ranges enable designs to break down multi-column experiences into simpler layouts according to available space.
Breakpoint sizes
Primer defines six breakpoints: xsmall (320px), small (544px), medium (768px), large (1012px), xlarge (1280px), and xxlarge (1400px). Breakpoints are used as a ruler for fine-tuning responsive experiences and are not tied to a specific min-width mobile-first media query approach.
Content and pane padding by breakpoint
Padding values for content and pane areas vary by breakpoint: xsmall through large use 16px for both content and pane; xlarge and xxlarge use 24px for content and 16px for pane. Padding is applied directly to the content or pane area, not to the parent container. A max-width at xlarge (1280px) includes the 24px padding, resulting in a visual max-width of 1232px for content.
App header behavior
The app header is GitHub's topmost bar containing global navigation, actions, and contextual elements like context region and local navigation. It may also contain system-level elements such as notification banners. The app header is never fixed to the top of the viewport; it scrolls with the rest of the page.