Getting Started

Quick Start

Add Griddle to your project via CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/skpaul/griddle@2.1.2/griddle.min.css">

Installation Options

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/skpaul/griddle@2.1.2/griddle.min.css">

Download the latest version from GitHub and include it in your project:

<link rel="stylesheet" href="path/to/griddle.min.css">

Install via package manager (if available):

npm install griddle-css
# or
yarn add griddle-css

Basic Usage

Create a grid container with the .grid class:

<div class="grid fr3">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

Customizing grid fractions

Control the number of columns with these classes:

.fr1 .fr2 .fr3 .fr4 .fr5 .fr6 .fr7 .fr8 .fr9 .fr10 .fr11 .fr12

Example: 3-column grid

Item 1
Item 2
Item 3
<div class="grid fr3">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

Responsive Grids

Best Practice: Desktop-First Approach

Griddle follows a desktop-first methodology. Start with a default base class (e.g., .fr3 or .fr4) that targets your primary desktop viewport (~1200px), then use responsive modifiers to simplify layouts as screens get smaller.

Example: <div class="grid fr4 fr3-md fr2-sm fr1-xs"> establishes a 4-column base for desktop, progressively reducing to 3, 2, and finally 1 column as the viewport narrows.

Griddle provides responsive breakpoints for different screen sizes:

Breakpoint Size Suffix Example
Extra Large ≥1400px -xl .fr3-xl
Large ≤1200px -lg .fr3-lg
Medium ≤992px -md .fr2-md
Small ≤768px -sm .fr2-sm
Extra Small ≤576px -xs .fr1-xs
Ultra Small ≤480px -us .fr1-us 
<div class="grid fr4 fr3-md fr2-sm fr1-xs">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</div>

Live Example: Responsive Grid

Resize your browser to see how this grid responds to different screen sizes:

Item 1
Item 2
Item 3
Item 4

This grid will show:

  • 4 columns on large screens
  • 3 columns on medium screens (≤992px)
  • 2 columns on small screens (≤768px)
  • 1 column on extra small screens (≤576px)

Auto Grid: Create grid with unknown fractions

The auto grid automatically adjusts column sizes based on available space:

<div class="grid auto"> ... </div>

Live Example: Auto Grid

Resize your browser to see how the auto grid adjusts:

Item 1
Item 2
Item 3
Item 4
Item 5
Item 6
Item 7

Control maximum columns at different breakpoints:
While using .auto, you can use the following classes to limit the number of fractions on each row-

.max1-sm .max2-sm .max3-sm .max4-sm .max5-sm .max6-sm .max7-sm .max8-sm .max9-sm .max10-sm .max11-sm .max12-sm 

<div class="grid auto max4-lg max3-md max2-sm max1-xs">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</div>

Live Example: Auto Grid with Limits

This auto grid has maximum column limits at different breakpoints:

Item 1
Item 2
Item 3
Item 4
Item 5
Item 6
Item 7
Item 8

This grid will show at most:

  • 4 columns on large screens (≤1200px)
  • 3 columns on medium screens (≤992px)
  • 2 columns on small screens (≤768px)
  • 1 column on extra small screens (≤576px)

Item Spanning

Control how many columns a grid item spans:

<div class="grid fr4">
  <div class="fr2">Spans 2 columns</div>
  <div>Normal column</div>
  <div class="fullwidth">Spans all columns</div>
</div>

Example: Item spanning

Spans 2 columns (fr2)
Normal column
Normal column
Spans all columns (fullwidth)
Normal column
Spans 3 columns (fr3)

Interactive Demo: Try Different Span Options

Normal
Interactive Item
Normal
Normal
Normal
Normal

Gap Utilities

Control the gaps between grid items with precision:

Row Gaps

<div class="grid fr3 rowgap-10">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

Column Gaps

<div class="grid fr3 colgap-20">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

Interactive Demo: Try Different Gap Sizes

Item 1
Item 2
Item 3
Item 4
Item 5
Item 6

Available gap classes: .rowgap-01 to .rowgap-40 and .colgap-01 to .colgap-40 (corresponding to 0.1rem to 4.0rem in 0.1rem increments)

Examples

Responsive Card Layout

<div class="grid fr4 fr3-md fr2-sm fr1-xs rowgap-15 colgap-15">
  <div class="card">
    <h3>Card 1</h3>
    <p>Card content</p>
  </div>
  <div class="card fr2 fr1-md">
    <h3>Wide Card</h3>
    <p>This card spans 2 columns on large screens</p>
  </div>
  <div class="card">
    <h3>Card 3</h3>
    <p>Card content</p>
  </div>
</div>

Live Example: Card Layout

Card 1

This is a standard card with some sample content.

Wide Card

This card spans 2 columns on large screens but only 1 column on medium screens and smaller.

Card 3

Another standard card with sample content.

Card 4

Yet another standard card with sample content.

Photo Gallery with Dense Packing

<div class="grid dense fr6 fr4-md fr3-sm fr2-xs">
  <div class="fr3 fr2-md fr1-sm">Landscape Photo</div>
  <div>Portrait Photo</div>
  <div class="fr2">Square Photo</div>
  <div>Portrait Photo</div>
  <div class="fr4 fr3-md fr2-sm">Panorama Photo</div>
</div>

Live Example: Photo Gallery

Landscape Photo
Portrait Photo
Square Photo
Portrait Photo
Panorama Photo
Portrait Photo
Portrait Photo
Square Photo

Notice how the dense class fills in empty spaces in the grid.

Browser Support

Griddle uses CSS Grid, which is supported by all modern browsers:

Chrome

57+

Firefox

52+

Safari

10.1+

Edge

16+

Note: For IE11 support, consider using a CSS Grid polyfill or fallback layout.