Integrate hgrid in Your Projects

Learn how you can set up hgrid in your Node.js driven projects, and how to customize its default settings.

Vue & NuxtJS

This recipe is tested with Vue v3.2.6 and NuxtJS v2.15

Check out the starter project on GitHub (Vue + Vite)

Method 1 (recommended)

Include with `@use`

1. For Vue + Webpack, install two packages: npm i sass sass-loader -D. For Vue + Vite, install only sass

2. Install hgrid: npm install hgrid-css -D

3. Create main.scss, for example in assets/scss/

4. Import main.scss into main.js:

  import './assets/scss/main.scss'

5. In main.scss, initialize hgrid from node_modules with @use:

@use 'hgrid-css/sass/hgrid'

// Add your own CSS or SCSS (if you have any) with @import and @use respectively:

@import 'css/partials/app-frame.css';
@use 'scss/partials/_theme.scss';

hgrid is now fully loaded into your project. If you want to leave out certain parts, use one @use rule for each hgrid partial to include.

  @use '~hgrid-css/sass/variables/variables'; // Required*
@use '~hgrid-css/sass/mixins/mixins'; // Required*
@use '~hgrid-css/sass/base/base'; // Required*

@use '~hgrid-css/sass/base/a11y';
@use '~hgrid-css/sass/layout/flex';
@use '~hgrid-css/sass/layout/containers';
// etc.

Important: See the recommended production build steps for our tips on optimizing the final output.

Customization (optional)

You can set your own theme colors and more by adding your own values to the hgrid variables (see the full list of options). Note that we use commas after the declarations instead of semicolons:

@use 'hgrid-css/sass/hgrid' with (
  $link-color: #ffe88d,
  $link-color-hover: #fff0b4,
  $container-max-width: 1600px,
  $link-underline-color: #ffe88d,
  $include-grid: false, // exclude CSS grid utilities from output
  $use-global-link-underlines: true // nicer text links
);

// Sass $variables aren't available globally. But hgrid's custom 
// properties reflect the most useful variables and are 
// available everywhere:

.alertbox {
  background: var(--bg-gray-dark);
  color: var(--text-color-secondary);
}

⚠️ Trying to execute any other code than @forward before @use won't compile. Read more about the @use rule over at sass-lang.com.

Access to Variables

If you need access to any $hgrid-variables in your project files you have to include them with @use 'hgrid-css/sass/variables/variables' as * at the top of each file/style section. However, this may be redundant because the most important variables are available as --custom-properties everywhere.

Read more about hgrid variables and custom properties. See also the alternative variable access method.

Method 2

Quick imports

2a. @import or @use in 'App.vue'

@import precompiled CSS or @use SCSS at the top of App.vue's <style> tag.

CSS

<style lang="css">
  @import '~hgrid-css/dist/hgrid.min.css';

  /* Other CSS classes from here down */
</style>

SCSS

Set up a style tag for scss in App.vue. Then use the description from Method 1 to @use hgrid.

<style lang="scss">
  @use 'hgrid-css/sass/hgrid' with (
    // optional config
  );
</style>

2b. Import prebuilt CSS in 'main.js'

import ‘~hgrid-css/dist/hgrid.min.css’

2c. Import prebuilt CSS to local stylesheet

At the top of a local CSS file, for example /assets/css/style.css you can import the full hgrid kit from node_modules:

  @import '~hgrid-css/dist/hgrid.min.css';

Alternative method for global variables

Previously we learned that hgrid $variables can be accessed in component files with the @use rule. Another way to access them is to make them available from vue.config.js like so:

module.exports = {
   css: {
     loaderOptions: {
       scss: {
         additionalData: `
           @import '~hgrid-css/sass/variables/_variables.scss';
         `
      }
    }
  }
}

Restart the dev server with npm run serve for config changes to take effect.

Note: Using global Sass variables may be redundant as you automatically have access to all of hgrid's custom properties that reflect the same variables. Read more about that here.

⚠️ Don't import anything here that won't be abstracted away in the build process. If you do, performance will be affected. The same styles will be included multiple times – once for every component and view.

React

This recipe is verified with React 17.0.1 and create-react-app 4.0.2.

Demo Project

Check out the starter project on GitHub.

Prerequisites

Install the Dart Sass package: npm i sass --save-dev
Install hgrid: npm i hgrid-css --save-dev
Rename index.css to index.scss (or create it in src/ if it doesn't exist.)
Rename App.css and other component files to use the file ending .scss.
Import your .scss files in index.js and the relevant component files:

  import './index.scss';

  import './App.scss';

Any files with the .scss extension imported in App.js will now be automatically compiled to CSS. Autoprefixer is a part of the hgrid project for broader browser compatibility, but in a React app from scratch you have to configure it yourself. Create-react-app and the starter project we link to above has Autoprefixer working out of the box.

Important: See the recommended production build steps for how to optimize the final output.

Initialization in index.scss

  @use '~hgrid-css/sass/hgrid'

hgrid is now fully loaded into your project. If you want to leave out certain parts, use one @use rule for each hgrid partial to include.

  @use '~hgrid-css/sass/variables/variables'; // Required*
@use '~hgrid-css/sass/mixins/mixins'; // Required*
@use '~hgrid-css/sass/base/base'; // Required*

@use '~hgrid-css/sass/base/a11y';
@use '~hgrid-css/sass/layout/flex';
@use '~hgrid-css/sass/layout/containers';
@use '~hgrid-css/sass/layout/auto-columns';
@use '~hgrid-css/sass/layout/helpers/background';

Configuration is optional. You can set your own theme colors and more by adding your own values to the hgrid variables (see the full list of options). Note that we use commas after the declarations, not semicolons:

  @use '~hgrid-css/sass/hgrid' with (
  $body-bg: #7056ce,
  $column-gutter-width: 1.2%,
  $container-max-width: 1680px,
  $link-color: #00a344,
  $link-color-hover: #00cc66,
  $link-underline-color: #daae00,
  $turn-off-link-decoration: true,
  $use-global-link-underlines: true // nicer links
  $include-grid: false, // exclude CSS grid utilities
);

// Add your own CSS or SCSS partials (if you have any) with @import and @use respectively:

@import 'css/vendors/tooltipz.css';
@use 'scss/partials/_theme.scss';

// Add other global styles from here down

// You have access to hgrid's custom properties
// https://hgrid.io/documentation/variables/

.example {
  background: var(--bg-dark);

  h1 {
    color: var(--text-color-secondary);
    font-size: 3rem;
  }
}

⚠️ Trying to execute any other code than @forward before @use won't compile. Read more about the @use rule over at sass-lang.com.

Usage of hgrid's utility classes in component files:

import './App.scss';

function App() {
  return (
    <div className="App container-max">
      <div className="row padding-top-150">
        <div className="column radius-6 bg-gray-light">Content</div>
        <div className="column radius-6 bg-dark text-white">Content here</div>
        <div className="column radius-6 bg-gray-darker text-white">More content</div>
        <div className="column radius-6 bg-white text-blue">Hello content</div>
      </div>
    </div>
  );
}

export default App;

If you need something from hgrid you can't get from the custom properties, @use any of the partials like this:

@use '~hgrid-css/sass/variables/variables' as var;
@use '~hgrid-css/sass/mixins/mixins' as mixin;

.ExcellentComponent {
  font-size: 20px;
  .column {
    padding: var.$column-gutter-width;
  }
}

@include mixin.viewport(phone-landscape) {
  .container-max {
    max-width: 96%;
  }
}

Our React starter project which is based on create-react-app automatically minifies and autoprefixes the CSS output. Read more in the docs. Remember hgrid's own recommendations for further optimalization of the production build.

Svelte

This recipe is tested with the SvelteKit beta

Demo Project

Check out the starter project on GitHub.

Manual Setup

Set up a new SvelteKit project from scratch with npm init svelte@latest my-app-name.

(Go to your project folder if you're not already there: cd my-app-name.)
Install dependencies with npm i.
Install Svelte's preprocessor: npm i -D svelte-preprocess
Install Sass: npm i -D sass.
Install hgrid: npm i -D hgrid-css
Change the file type of SvelteKit's app.css to app.scss (how you name it is up to you).

Add preprocessing config:

import preprocess from 'svelte-preprocess'

const config = {
  preprocess: preprocess({
    renderSync: true,
    implementation: 'sass'
  })
}

export default config

Initialize hgrid in app.scss with your own config if required:

@use 'hgrid-css' with (
  // optional config goes here, for example:
  $body-bg: #7056ce,
  $link-color: #00a344,
  $link-color-hover: #00cc66,
  $container-max-width: 1680px,
  $column-gutter-width: 1.2%,
  $link-underline-color: #daae00
  $turn-off-link-decoration: true,
  $use-global-link-underlines: true // nicer links
  $include-grid: false, // exclude CSS grid utilities
);

// Other global styles from here down
// ...

In your terminal: npm run dev
The project now runs on localhost:3000 with hgrid styling.

While scss from hgrid will compile without any further configuration, adding <style lang="scss"> to your style tags is needed if you wish to write custom scss in Svelte components.

Important: See the recommended production build steps for our tips on optimizing the final CSS output.

Eleventy

This recipe is tested with 11ty v2.0.1

Demo Project

Check out the starter project on GitHub.

Project Setup from Scratch

Let's set up a minimal 11ty project from scratch and install hgrid-css. 11ty requires Node.js version 10 or higher.

Step 1

Point your terminal to a new project folder and install 11ty:

$ npm init -y && npm install --save-dev @11ty/eleventy

Step 2

Install some required packages (as dev dependencies):

hgrid-css
autoprefixer
npm-run-all
postcss
postcss-cli
sass
sass-loader

$ npm install --save-dev hgrid-css autoprefixer npm-run-all postcss postcss-cli sass sass-loader

Step 3

Create the 11ty config file eleventy.js at the root of the project folder and add this content:

module.exports = (eleventyConfig) => {

  eleventyConfig.addPassthroughCopy('src/assets/img/icon.png')

  return {
    passthroughFileCopy: true,
    markdownTemplateEngine: 'njk',
    templateFormats: ['html', 'njk', 'md', 'js'],

    dir: {
      input: 'src',
      output: '_public'
    }
  }
}

Here we tell 11ty to copy our favicon from the input directory (src) to the build output directory (_public) when it builds the final files. We also set up a config object with information about which template engine and formats we wish to use as well as the names of our input and output directories (their naming is up to you).

Step 4

Create the folder src, the directory where 11ty will find the source code to compile and copy to the _public directory. Inside src, create three other directories: _includes, assets and scss. Also, create the file index.njk. Remember to install a Nunjucks code editor plugin to obtain syntax highlighting.

Nunjucks is a templating engine for JavaScript, similar to ESJ, Jade and Mustache. .njk files work with ordinary HTML and Markdown syntax in addition to inline JavaScript in {{ tokenFormat }} or as {% expression blocks %}. Data and variables can be set with front matter at the top of a .njk file. Your index.njk could look like this:

---
layout: layout/base.njk,
pageTitle: The Grapes of Wrath by John Steinbeck,
meta: {
  author: John Steinbeck,
  description: 'A page about my latest novel, called "The Grapes of Wrath"'
}
---

<html>
  <head>
    <title>{{ pageTitle }}</title>
    <meta name="author" content="{{ meta.author }}">
    <meta name="description" content="{{ meta.description }}">
  </head>

  <body>
    <h1>{{ pageTitle  }}</h1>
  </body>
</html>

Step 5

As a proof of concept for 11ty/Nunjucks' templating engine, let's use a base layout template for our page and extract the <head> section into a separate file. Notice how we refereced the base template at the top of index.njk (step #4). In the _includes directory, create a folder named layout. Inside, add a file called base.njk:

<!DOCTYPE html>
<html lang="en-US">
  {% include "layout/partials/head.njk" %}
  <body>
    {{ content | safe }}
  </body>
</html>

As the html, head and body tags are now taken care of by our new partial, we can simplify index.njk:

---
layout: layout/base.njk,
pageTitle: The Grapes of Wrath by John Steinbeck,
meta: {
  author: John Steinbeck,
  description: 'A page about my latest novel, called "The Grapes of Wrath"'
}
---

<main>
  <h1>{{ pageTitle  }}</h1>
</main>

Step 6

In your layout folder, create a new folder named partials with a file called head.njk in it. Cut the <head> code from index.njk (step #4) and paste it into this file. Add this at the top of the file:

{%- set siteTitle = '11ty starter project with hgrid-css' -%}

You're soon ready to start the local development server so you can see your website in the browser. Just one more step.

Step 7

We need to add some scripts to our package.json:

"scripts": {
  "watch:sass": "sass --no-source-map --watch src/scss/main.scss:_public/css/style.css",
  "watch:eleventy": "eleventy --serve",
  "build:sass": "sass --no-source-map --style=compressed src/scss/main.scss:_public/css/style.css",
  "build:eleventy": "eleventy",
  "prefix:css": "postcss --use autoprefixer --no-map -b 'last 2 versions' _public/css/style.css -o _public/css/style.css",
  "start": "npm-run-all build:sass --parallel watch:*",
  "build": "npm-run-all build:* prefix:css"
}

What's going on here?

We're setting up automatic compilation for hgrid with Sass and drop the resulting CSS file in _public/css/.
When you run npm run start in your terminal, 11ty will spin up a development server with hot browser reloading. This is the eleventy --serve part.
It will watch for changes in files in the src (input) directory.
If code is changed, 11ty will recompile everything and output the files to _public.
When the build command is ran, PostCSS' Autoprefixer plugin will do its thing before the final CSS will be minified.

After running npm run start, open localhost:8080, which is 11ty's default port in development mode. You should see your unstyled index page with all template variables in place. Time to add CSS with hgrid!

Step 8

In /src/scss, add a new file called e.g. main.scss. At the top of the file, initialize hgrid with the @use rule, as seen multiple times before in previous recipes. Note that we have to give 11ty the full path in order to find hgrid:

@use './../../node_modules/hgrid-css/sass/hgrid.scss' with (
  // optional config goes here, for example:
  $body-bg: #7056ce,
  $link-color: #00a344,
  $link-color-hover: #00cc66,
  $link-underline-color: #daae00,
  $include-grid: false, // exclude CSS grid utilities from output
  $use-global-link-underlines: true // nicer links
);

// Other global styles from here down
// ...

⚠️ Trying to execute any other code than @forward before @use won't compile. Read more about the @use rule over at sass-lang.com.

Check your browser again and you should now see that hgrid styling has been applied. Add in a few extra hgrid utilities to see how they work:

<main class="container-max padding-80 tablet-portrait-pr-30 tablet-portrait-pl-30">
  <h1 class="text-center">{{ pageTitle  }}</h1>
</main>

Now you have a centered title in a container with a max-width and some padding that is reduced on the right and left sides on tablet sized viewports.

Important: See the recommended production build steps for our tips on optimizing the final output.

Step 9

A last detail is to add a favicon and any other images you may need in the /assets/img/ directory. Update head.njk like this:

<link rel="icon" type="image/png" href="/assets/img/icon.png">

The assets folder is where you would also usually put fonts etc. that aren't supposed to be compiled by 11ty (but just passed straight through to the _public folder). Remember to reference files and folders you want to include as addPassthroughCopy in eleventy.js.

You're done! Run npm run build and deploy everything in _public to your preferred static website hosting provider or content delivery network.

11ty will exclude from the build process any files or folders in the input (src) directory that are referenced in your .gitignore. If you need to git-ignore something you want to include in the 11ty output, add eleventyConfig.setUseGitIgnore(false); to eleventy.js and create instead a .eleventyignore file in the project root where you indicate what 11ty should exclude. More info.

Astro

This recipe is verified with Astro beta 0.0.12

Demo Project

Check out the starter project on GitHub.

Setup

Of all the frameworks on this page, Astro undiscutably offers the easiest process of integrating hgrid. It ships with automatic Sass support, so there's nothing extra to install — except hgrid-css itself.

In your terminal of choice, cd into your project folder and install hgrid-css with npm i -D hgrid-css. Rename Astro's default global.css file in the /public/style/ folder to global.scss and initialize hgrid like this at the top of the same file:

@use 'hgrid-css/sass/hgrid' with (
  // optional config goes here, for example:
  $body-bg: #7056ce,
  $link-underline-color: #daae00,
  $container-max-width: 1680px,
  $turn-off-link-decoration: true,
  $include-grid: false, // exclude CSS grid utilities from output
  $use-global-link-underlines: true // nicer text links
);

// Other global styles and from here down
// ...

Voilà, that's it.

You can immediately style your HTML with hgrid utilities anywhere in your .astro files.

CSS in Astro can be located anywhere, as global stylesheets, in components or in page files. SCSS styling inside of Astro components is done by adding a <style lang="scss"> anywhere. Multiple style tags per file are permitted. By default, all Astro component styles are scoped, meaning they only apply to the current component. To create global styles from a locally scoped context, add the :global() wrapper, e.g. :global(.my-style) { ... }. Styles are automatically extracted and optimized in the final build.

Important: See the recommended production build steps for tips on additional optimization.

As always, access to internal $hgrid-variables in components requires you to first include them with @use 'hgrid-css/sass/variables/variables' at the beginning of your style sections. But you may not need this because the most important variables are available as --custom-properties without any @import or @use.

← Previous: Installation

Next: Layout →

Integrate hgrid in Your Projects

Vue & NuxtJS

Method 1 (recommended)

Include with @use

Customization (optional)

Access to Variables

Method 2

Quick imports

2a. @import or @use in 'App.vue'

CSS

SCSS

2b. Import prebuilt CSS in 'main.js'

2c. Import prebuilt CSS to local stylesheet

Alternative method for global variables

React

Demo Project

Prerequisites

Initialization in index.scss

Svelte

Demo Project

Manual Setup

Eleventy

Demo Project

Project Setup from Scratch

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

Step 7

Step 8

Step 9

Astro

Demo Project

Setup

Include with `@use`