@olefjaerestad/griddie v0.0.3
Griddie
Another CSS grid library. That's all.
Table of contents
Use
npm i @olefjaerestad/griddie
The package structure looks like this:
How to import the files into your project will depend on which bundler, if any, you're using. See Use with vanilla CSS and Use with Scss/Sass for examples of common patterns.
Vanilla CSS
Without bundler:
/* style.css */
@import './node_modules/@olefjaerestad/griddie/build/style.css';
With a bundler that supports importing CSS from node_modules, the import statement should probably look something like this (depending on the bundler configuration):
/* style.css */
@import '~@olefjaerestad/griddie/build/style.css';
/* or */
@import '@olefjaerestad/griddie/build/style.css';
/* or */
@import '~@olefjaerestad/griddie';
/* or maybe even */
@import '@olefjaerestad/griddie';
Scss/Sass
If you use Sass, you probably want to import the Sass version of Griddie:
/* style.scss */
@import '@olefjaerestad/griddie/build/style.scss';
Using Sass, you can choose to import only the functionality you need:
/* style.scss */
/**
* Variables must be defined before importing the other partials.
* If you don't provide Sass variables yourself (see 'Configure with Sass'),
* _variables.scss must always be imported.
*/
@import '@olefjaerestad/griddie/build/partials/_variables.scss';
@import '@olefjaerestad/griddie/build/partials/_grid.scss';
@import '@olefjaerestad/griddie/build/partials/_cell.scss';
@import '@olefjaerestad/griddie/build/partials/_offset.scss';
If you use Sass, you can configure the variables used by Griddie. See Configure with Sass.
Markup
Griddie uses the concept of grids and cells. A cell must always be a direct child of a grid, and a grid can consist of zero or more cells. At its simplest, you can add a horizontal grid with cells like this:
<div class="g-x">
<div class="c-4">I am a cell with a width of 4 columns.</div>
<div class="c-8">I am a cell with a width of 8 columns.</div>
</div>
Available classes
Grid
.g-x
: Horizontal grid. Can be combined with vertical grid..g-y
: Vertical grid. Can be combined with horizontal grid.
Cell
.c-6
: A cell spanning 6 columns or rows, depending on whether parent grid is horizontal or vertical. If parent grid is both horizontal and vertical, the cell spans both 6 columns and rows..c-6-x
: A cell spanning 6 columns, independently of whether parent grid is horizontal or vertical or both..c-6-y
: A cell spanning 6 rows, independently of whether parent grid is horizontal or vertical or both..c-md-6
: A cell spanning 6 columns or rows on medium viewport widths and above, depending on whether parent grid is horizontal or vertical. If parent grid is both horizontal and vertical, the cell spans both 6 columns and rows..c-md-6-x
: A cell spanning 6 columns on medium viewport widths and above, independently of whether parent grid is horizontal or vertical or both...c-md-6-y
: A cell spanning 6 rows on medium viewport widths and above, independently of whether parent grid is horizontal or vertical or both.
Cell offset (aka cell positioning)
By default, cells will flow naturally. Use these classes to explicitly position them.
.o-6
: Use on a cell to force it to start at grid line 6. If parent grid is horizontal, this will offset the element horizontally. If parent grid is vertical, the element will be offset vertically. If parent grid is both horizontal and vertical, the element will be offset both horizontally and vertically..o-6-x
: Use on a cell to force it to start at grid line 6 in the horizontal axis, independently of whether parent grid is horizontal or vertical or both..o-6-y
: Use on a cell to force it to start at grid line 6 in the vertical axis, independently of whether parent grid is horizontal or vertical or both..o-md-6
: Use on a cell to force it to start at grid line 6 on medium viewport widths and above. If parent grid is horizontal, this will offset the element horizontally. If parent grid is vertical, the element will be offset vertically. If parent grid is both horizontal and vertical, the element will be offset both horizontally and vertically..o-md-6-x
: Use on a cell to force it to start at grid line 6 in the horizontal axis on medium viewport widths and above, independently of whether parent grid is horizontal or vertical or both..o-md-6-y
: Use on a cell to force it to start at grid line 6 in the vertical axis on medium viewport widths and above, independently of whether parent grid is horizontal or vertical or both.
In the examples above,
md
can be replaced with any key in$breakpoints
.6
can be replaced with any number between1
and$maxColumns
. See Configure with Sass for more info.
Configuration
Griddie uses CSS custom properties, which allow you to configure some of its behaviour.
The properties can be defined on any parent element of .g-x
or .g-y
(including itself and :root)
and Griddie will use them. Below is a list of the properties you can use and their default values.
.g-x,
.g-y {
/* The number of columns in a grid. Should not exceed $maxColumns (see 'Configure with Sass'). */
--columns: 12;
/* The number of rows in a grid. Should not exceed $maxRows (see 'Configure with Sass'). */
--rows: 12;
/* Horizontal space between columns. */
--gap-x: 1rem;
/* Vertical space between rows. */
--gap-y: 1rem;
/**
* Addtionally, based on your $breakpoints (see 'Configure with Sass'), you can use properties in
* the following format to overwrite spacing at specific breakpoints. These have no default values:
*/
--gap-sm-x
--gap-md-y
--gap-lg-x
}
Configure with Sass
If you're using the Sass version of Griddie, you can configure additional variables/options by defining these before you import the Griddie CSS. Below is a list of these variables and their default values:
/*
* Used to generate cell and offset classes, e.g. `.c-md-4` and `.o-lg-2`.
* You can add/remove as many breakpoints as you need here.
* More breakpoints = larger file size.
*/
$breakpoints: (
'sm': 480px,
'md': 720px,
'lg': 960px,
);
/*
* Used to generate cell and offset classes, e.g. `.c-4` and `.o-2`.
* You can increase/decrease these as much as you need.
* These do not have to be the same. For example, if you only need
* horizontal grids, you could reduce $maxRows to 0 to reduce file size.
* Higher numbers = larger file size.
*/
$maxColumns: 12;
$maxRows: 12;
Browser support
Browser | Supported? |
---|---|
Chrome >= 66 | ✅ |
Edge >= 16 | ✅ |
Firefox >= 61 | ✅ |
Internet Explorer | ❌ |
Opera >= 53 | ✅ |
Safari >= 12.1 | ✅ |
Chrome for Android > 66 | ✅ |
Firefox for Android > 61 | ✅ |
Opera for Android > 47 | ✅ |
Safari for iOS > 12 | ✅ |
Dev
If you want to work with the source code, all you need to do is:
npm i
npm run dev
Tests will run on commit. If any of the tests fail, the commit will fail. To bypass, pass
--no-verify
. Example:git commit -m "WIP" --no-verify
.
Tech stack
- Bundling: esbuild
- Dev server: fastify
- Hot reloading: @olefjaerestad/hmr
- Testing: Jest and Playwright
- Documentation: Storybook
Build for prod
npm i
npm run build
Build docs
Build a new version of the Griddie documentation website.
npm i
npm run build:docs
Testing
npm i
Unit tests
npm run test:unit
Watch mode:
npm run test:unit -- --watch
E2E (End-To-End) tests
npm run test:e2e
All tests
npm run test
Interactive documentation
npm run storybook
TODO:
- Add e2e tests.