(opens in a new tab)

Breakpoints & Grid

Responsive layout grids and breakpoints that adapt fluidly across devices and screen sizes.

Column grids are used to organize layouts, components, and content into structured hierarchies. This structure ensures consistent alignment and distribution across all views. Built on responsive breakpoints, the grid adapts smoothly from mobile screens to ultrawide monitors.

Visualization of the grid system using columns, gutters and margins
Visualization of the grid system using columns, gutters and margins

Explore the Grid

Visit our interactive Grid Playground(opens in a new tab) to see the grid system in action.

Copy link to headline:Grid

The grid system consists of three core building blocks:

  1. Columns

    Available width is divided into up to 12 columns. Elements define how many columns they span, and overflowing elements wrap to the next row.

    Maximum columns adapt dynamically based on the active breakpoint. See breakpoints below for details.

  2. Gutters / Gaps

    Elements within the grid are separated by predefined gutter spacing.

  3. Margins

    Unified outer margins provide dynamic padding around grid containers, keeping content properly indented from viewport edges.

Copy link to headline:Usage

Add the onyx-grid CSS class to create a grid container. Use column-span classes on child elements to control sizing:

  1. Specific number of columns

    Use onyx-grid-span-<number> to span a fixed number of columns:

  2. Full width

    Use onyx-grid-span-full to span all available columns across any breakpoint:

  3. Specific breakpoints

    To adjust column span at specific breakpoints, use onyx-grid-<breakpoint>-span-<number>. The element will span <number> of columns for that <breakpoint> and larger.

    Combine breakpoint-specific classes with a base onyx-grid-span-<number> class:

  4. Custom container

    The grid system is built on CSS container queries(opens in a new tab). Each grid evaluates breakpoints relative to its nearest container ancestor.

    OnyxPageLayout, OnyxAppLayout, and OnyxSidebar set up container queries automatically.

    To create a custom container, set the container-type(opens in a new tab) CSS property. This is useful when nesting grids inside OnyxModal or custom widgets:

Copy link to headline:Grid margin

Outer grid margins are applied automatically by OnyxPageLayout. To apply them manually, use the .onyx-grid-layout utility class:


Copy link to headline:Customization

Customize grid behavior by setting utility classes on the root application element:

  1. Max width

    By default, the grid expands across the full viewport width. To preserve readability on wide displays (e.g. 1440px or 1920px+), limit content width using max-width utility classes. Components like OnyxNavBar and OnyxBottomBar adapt automatically.

    Apply one of the following classes:

    none
    Max. widthnone
    CSS classnone (default)
    md
    Max. width1440px
    CSS classonyx-grid-max-md
    lg
    Max. width1920px
    CSS classonyx-grid-max-lg
  2. Alignment

    When a max-width class is set, align the grid container to the left or center:

    left
    Alignmentleft
    CSS classnone (default)
    center
    Alignmentcenter
    CSS classonyx-grid-center
  3. Max columns

    The grid defaults to 12 columns. On wide displays (breakpoint lg and above), you can expand the column count to 16 or 20:

    12
    Max. columns12
    CSS classnone (default)
    16
    Max. columns16
    CSS classonyx-grid-lg-16
    20
    Max. columns20
    CSS classonyx-grid-xl-20

Copy link to headline:Breakpoints

Breakpoints define width thresholds where page or component layouts refactor for smaller or larger screens:

2xs
Width320px to 576px
Max. grid columns4
xs
Width577px to 768px
Max. grid columns8
sm
Width769px to 992px
Max. grid columns8
md
Width993px to 1440px
Max. grid columns12
lg
Width1441px to 1920px
Max. grid columns12 or 16
xl
Width1921px and beyond
Max. grid columns12, 16 or 20

The minimum supported viewport width is 320px. Screens narrower than 320px are not officially supported.

Copy link to headline:Usage

In custom layouts or components, use SCSS mixins to query screen or container widths:

  1. Media queries

    To apply styles based on the viewport width, use the breakpoints.screen() SCSS mixin:

  2. Container queries

    To apply styles based on the parent element width, use the breakpoints.container() SCSS mixin. Ensure the element has container-type defined.

    When defining both min and max for the same breakpoint, include an offset parameter:

  3. Usage in code

    To access breakpoint values in TypeScript or JavaScript, import ONYX_BREAKPOINTS: