Menu
Menu Sheet Overlay
Search
Search Sheet

Responsive Grid

    Table of Contents #

    Introduction #

    Until all commonly used browsers support the CSS Grid Layout, the Mobify SDK needs to provide a default for responsive projects. A consistent system makes things simpler for everyone.

    This guide will introduce you to the Mobify responsive grid library, Susy 3, and provide direction regarding best practices for usage. You’ll also find sample code implementations that you can use in your projects.

    Responsive Best Practices #

    If you haven’t already, read up on Mobify’s Responsive Best Practices.

    The SDK has some default breakpoints in place for you in _variables.scss: $medium-breakpoint, $large-breakpoint, and $x-large-breakpoint. These names are Mobify convention and will be used in the examples below.

    Why Susy? #

    Susy is a SASS library that helps you build readable, robust responsive grid systems. The library has been developed and maintained for over 8 years by Miriam Suzanne, a prominent contributor in the web development community.

    We’ve chosen Susy for a number of reasons:

    Getting Started #

    Susy Setup #

    Susy is already installed for you as a Node package. In your project’s _variables.scss, you’ll find a $susy Sass map that sets a couple defaults. Read more about these options, and others you can set.

    // Responsive Grid Configuration
    $susy: (
        columns: susy-repeat(4),
        gutters: 12px
    );
    

    Columns: The number of columns in your layout.

    Gutters: The width of your gutters/margins. Providing in a unitless value will give you fluid gutters. For example, using 0.5 will give you a fluid gutter half (0.5) the size of a single column, while 12px will give you a static gutter that’s 12px wide.

    This is all you need to set up to start using Susy! For projects that use different grids depending on device width, read on below for a bit more setup.

    Adding Breakpoints #

    If you are working on a project that switches grid configurations at different breakpoints, you’ll want to set up a few more variables! The final result can seem a bit ✨magical✨, so let’s walk through the steps:

    1. Set up a configuration for each non-default grid layout If you want to switch to a 12 column grid with 24px gutters at your large breakpoint, you might add:

    $large-config: (
        columns: susy-repeat(12),
        gutters: 24px
    )
    

    to _variables.scss. Note: Your “default” grid configuration is what you have declared in your $susy map.

    You can add as many configs as you want: these are just alternate versions of the “default” $susy map. Make sure to follow the ${breakpoint}-config naming convention, where breakpoint is the name of your breakpoint.

    2. Use susy-breakpoint in place of a regular media query

    The susy-breakpoint mixin replaces a traditional media query (e.g.: @media screen ...) and takes two arguments: a breakpoint and a config that you’ve defined.

    It will output an @media block that has a config’s values scoped within it. We’ve set up our $large-config variable above, so now we can use it in the mixin along with our $large-breakpoint variable:

    // _cool-component.scss
    
    .c-cool-component {
        ...
    
        @include susy-breakpoint($large-breakpoint, $large-config) {
            ...
        }
    }
    

    3. Bonus Step

    If you’d like to be even more terse, you can use Sass’s variable arguments to group your breakpoint and config variables together, like so:

    // _variables.scss
    
    // Breakpoint Variables
    $large-breakpoint: 1000px;
    
    // Breakpoint Layouts
    $large-config: (columns: susy-repeat(12), gutters: 24px);
    
    // Susy-Breakpoint Variables
    $large: $large-breakpoint, $large-config;
    
    
    // _cool-component.scss
    
    .c-cool-component {
        ...
    
        @include susy-breakpoint($large...) {
            // ✨MaGiC✨
            ...
        }
    }
    

    Remember to keep your responsive variables and grid variables grouped together!

    Grid Usage #

    Now that we’re all set up, it’s time to use Susy!

    Span #

    Use the @span function to set an element to span a number of columns. You can use it with width, flex-basis, margin, or any other CSS rule that accepts a number. If you pass a parameter larger than 1, Susy will add in intermediate gutter spacing.

    .c-cool-component {
        float: left;
        // 2-up on an 8 column grid, with added spacing
        // for 3 intermediate gutters
        width: span(4);
    }
    

    The Susy docs explain how to add more parameters for context, nesting and other use cases.

    Note: Susy2 included a container mixin that helped clearfix for your floats, but this was removed in Susy3. If you’re using Susy with float, we’ve built our own @include container mixin into the SDK that provides similar functionality. It gets imported into your project in app/stylesheet.scss along with the other Susy mixins.

    Gutter #

    Use the @gutter function to add gutter math to a CSS rule. For example, adding margin-right: gutter() to a component will set the margin-right of that element to be the width of a gutter. Above, we started setting up our layout, but we didn’t add gutter spacing in between each instance of cool-component. We can use gutter to do that:

    .c-cool-component {
        float: left;
        width: span(4); // 2-up on an 8 column grid
        margin-right: gutter(); // add in the gutter
    
        &:nth-child(2n) {
            margin-right: 0; // remove the gutter on the last item
        }
    }
    

    Read more about the gutter function on the Susy docs.

    Examples #

    Below, you’ll find some examples of how you might use Susy in your project.

    Components #

    Easily make your components responsive!

    // We want 2-up styling on smaller screens where our grid is 8 columns wide,
    // and 4-up styling on larger screens that use a 12 column grid.
    
    .c-cool-component {
        float: left;
        width: span(4);
        margin-right: gutter();
    
        &:nth-child(2n) {
            margin-right: 0
        }
    
    
        @include susy-breakpoint($large...) {
            width: span(3);
    
            &:nth-child(4n) {
                margin-right: 0;
            }
        }
    }
    

    Templates #

    Use Susy for layouts or component adjustments!

    // We want to add a sidebar to our template, and make sure that our
    // component fills up the rest of the space in the 8 column grid.
    
    .t-template__sidebar {
        float: left;
        width: span(2);
        margin-right: gutter();
    }
    
    .t-template {
        .c-cool-component {
            float: right;
            width: span(6);
        }
    }
    

    Utility Classes #

    Use Susy for one-off styling! For example, you could implement this as an alternative to the solution above:

    // utilities/_grid.scss
    
    .u-grid-span-6 {
        width: span(6);
        margin-right: gutter();
    }
    
    .u-grid-last {
        margin-right: 0;
    }
    
    // template.jsx
    <section className="t-template__main">
        <CoolComponent className="u-grid-span-6 u-grid-span-last" />
    </section>
    <aside className="t-template__sidebar">...</aside>
    

    FAQ #

    Q: Do I need to use @susy-breakpoint for all my media queries?

    A: @susy-breakpoint is only necessary if you are planning on using Susy functions that depend on certain grid math in your query. Otherwise, feel free to use @media for your queries.

    Q: Where can I go if I need help answering a question?

    A: If you can’t find the answer here, try checking the Susy Docs, or do a search on StackOverflow.