Building a website with a grid layout and components

You are looking for a way to create a website with a grid layout? You won’t start all over with one of the old CMS which force you into a certain technology stack? In this tutorial we will guide you through the creation of a grid layout using Storyblok right after you’ve done the quickstart using the rendering service - if you’ve choosen the API/SDK version you can still have a look at this tutorial since only the source code for the Grid and Columns will be different.

What we will do:

  • Adding Bootstrap so we got a Grid (you can do this with any css you want).
  • Answering the question: “Why do we want a grid?”.
  • Setting up a grid component in Storyblok.
  • Creating the grid components source code.
  • Setting up column component nested in the grid component.
  • Creating the column components source code.
  • Adding a teaser into one of the columns.

Adding Bootstrap

We will use Bootstrap since most of you will already know that or already had their hands on it at least once. For simplicity we will add the grid system of Bootstrap using the Bootstrap Customizer - you could also simply add the dependency using npm and only import the modules you need.

Let’s create the file /source/scss/components/above/_grid.scss with the following content:

@import url('');
create your a grid.scss

This will load the bootstrap-grid-only.css for you directly from a CDN - You can change this by simply replacing the line above with your real CSS. Have a look at another article from us about how to optimize your website.

Why do we want a grid?

Initially, the trend, after the first iPhone was launched, was to build separate sites depending on whether a person visits the site from desktop or a mobile device. At first it seams easier from a development perspective, but only one of the downsides was the increasing maintenance costs because you simply doubled your website.

The main points for developing a responsive website are:

A grid layout

2010, Web designer Ethan Marcotte first introduced the term “responsive design”, you can read more about it in an article of him and since than the idea went from a static second version to completely flexible and fluid layout that adapt to almost any screen.

You can save yourself and your customer time during:

  1. Prototyping
  2. Development
  3. Maintenance

Setting up a grid component in Storyblok

We will start right after you’ve completed the quickstart - if you didn’t do that already we’ve prepared a walkthrough for you.

Simply press “Add component”, enter grid and press “create new” as you’re editing a Story. The Schema for a grid in Storyblok will look as simply as it is - it can contain other components so our field typ will be components and we will name this field columns. You can also restrict which components should be allowed in that field - for this you can have a look at the “advanced settings” of this field.

setting up a grid component

Guess what - that’s it.

Creating the grid components source code

Before we start make sure you’ve your local dev environment ready to start and executed following command in that directory to fire up your local web-server.

npm run dev

Since we named the component in Storyblok “grid” we will also create a component in your local project folder /views/components/_grid.liquid with the following content:

{{ blok._editable }}
<!-- Default Bootstrap Grid HTML -->
<div class="container">
  <div class="row">
    <!-- Loop through all the components contained in the columns field -->
    {% for blok in blok.columns %}
      <!-- include all components according to their name -->
      {% include blok.component with blok: blok %}
    {% endfor %}

This short snippet is the basic layout of a Grid in Bootstrap and the inner part is nothing more than a loop followed by a include of the inherit components. If you’re not familiar with the basics of liquid or want to know more about Storyblok specific Liquid Tags, Blocks and Drops you can read them whenever you want.

Setting up column component nested in the grid component.

Good job! You came a long way down here. Now let’s create another component by clicking on “Add Component” - this time in your grid component not in the root itself, enter column and press “create new” again. You now should have the following screen.

create your a grid.scss
  1. The newly created column component.
  2. Breadcrumbs so you see that you’re currently in your grid.

Don’t mind if you’ve created the column component in your root - you can simply cut it there and add it to your grid.

You can now define the Schema of your column component - simply click on the component you want to edit and press the Icon next to its name or press “Add new schema key”.

We will go with the key body and also of the type components as we got it in the grid component before.

Creating the column components source code.

Let’s create the /views/components/_column.liquid file and let’s add the HTML of a Bootstrap column to it.

{{ blok._editable }}
<!-- Default Bootstrap Column HTML -->
<div class="col-md-6">
  <!-- Loop through all the components contained in the body field -->
  {% for blok in blok.body %}
    <!-- include all components according to their name -->
    {% include blok.component with blok: blok %}
  {% endfor %}

this short snippet here is the basic HTML of a Column in Bootstrap - you can change this to your own HTML for your column. If you want to also allow to define the width of a column - different to md-6 - you can have a look at the end of this tutorial and discover how we used Storybloks Datasources for this.

Adding a teaser into one of the columns.

Last step is to add a the teaser from the quickstart in your columns body. Simply press “Add Component” in the field “body” of your column component and select the teaser component in the overlay. one final step - press save to trigger a reload of your Story and see your final result!

adding a teaser into a grid

Bonus: Change the width of a column using a datasource.

One data source is simply a collection of key-value pairs (KVP). There are 3 different Types of Datasources which can be used:

  • Self: Are directly defined at field level and can not be reused.
  • Internal: Are those you can create yourself by pressing on Datasource on the main navigation.
  • External: External API’s or JSON file in the following structure.

We’ve prepared the JSON for this already so you can directly add it to a new field in your column component.

All we now need to change is the way we use use the width field of our column component - currently we actually don’t use it.

{{ blok._editable }}
<!-- Default Boostrap Column HTML -->
<div class="{{blok.width|default:'col-md-6'}}">
  <!-- Loop through all the components contained in the body field -->
  {% for blok in blok.body %}
    <!-- include all components according to their name -->
    {% include blok.component with blok: blok %}
  {% endfor %}

As you can see we’ve only changed the hardcoded class “col-md-6” to the value of width with the fallback col-md-6. After changing the /views/components/_column.liquid all we have to do is to select other widths in Storyblok to change your layout.

What did you just learn?

  • ✓ Why do I want a grid?
  • ✓ Adding a Component with the “Components” field type
  • ✓ Dynamic rendering of components inside other components.
  • ✓ Use other field types
  • ✓ Adding Datasources to your fields.

I hope you enjoyed this tutorial and I would be happy to receive feedback! You can find the source code using the release list on Github: Kickstart - Releases.

More to read...

About the author

Dominik Angerer

Dominik Angerer

A web performance specialist and perfectionist. After working for big agencies as a full stack developer he founded Storyblok. He is also an active contributor to the open source community and one of the organizers of Stahlstadt.js.