Variables

Hgrid comes with two types of variables: Sass $variables for internal use and customization, and CSS --custom-properties, accessible from anywhere in your project.

File locations: sass/variables/_variables.scss and sass/variables/_custom-properties.scss (GitHub)

Internal variables

These are some of the options that are configurable with the @use rule in sass or scss files:

  @use 'hgrid-css/sass/hgrid' with (
  $theme-color-primary: #ffe88d,
  $theme-color-secondary: #fff0b4,
  $link-underline-color: #ffe88d,
  $container-max-width: 1680px,
  $custom-stack-point: 572px,
  $include-grid: false, // exclude CSS grid utilities from output
  $use-global-link-underlines: true // nicer link styling
);

This overwrites hgrid's defaults with your custom values. Notice the use of commas instead of semicolons.

See the full list on GitHub.

Internal variables aren't available in your project files unless you reference their file with @use. Every partial from hgrid can be accessed this way. A clear use case is to get access to the viewport mixin to help keep media queries consistent:

  @use 'variables/variables' as *;
@use 'mixins/mixins' as mixin;

.fantastic-component {
  color: $text-color-primary;
  background: $bg-gray-light;

  @include mixin.viewport(phone-landscape) {
    color: red;
  }
};

See also: How to integrate hgrid in your project as a Node module

Custom properties

As we have seen above, Sass variables must be referenced with @use in every file you want to use them. To avoid this overhead, and to allow easy manipulation with JavaScript, hgrid exposes essential internal variables as CSS custom properties. They are by default available everywhere, via the global :root pseudo-selector (equivalent to the html element).

The custom properties get their values from internal hgrid $variables. Their values will reflect your @use customization described above. In your css, scss or component files you can use the custom properties as is, overwrite them, and manipulate them with JS.

Here are a few of the custom properties available, with their corresponding internal variable:

  :root {

  // Theme Colors

  --theme-color-primary: #{$theme-color-primary};
  --theme-color-secondary: #{$theme-color-secondary};
  --theme-color-tertiary: #{$theme-color-tertiary};

  // Generic Colors

  --color-light: #{$color-light};
  --color-dark: #{$color-dark};

  // Text Colors 

  --text-color-primary: #{$text-color-primary};
  --text-color-secondary: #{$text-color-secondary};
  --text-color-tertiary: #{$text-color-tertiary};

  // Focus outline (:focus)

  --focus-border-color: #{$focus-border-color};
  --focus-border-weight: #{$focus-border-weight};

}

Full list on GitHub.

One use for custom properties is color theming for your site. Add a data property and you can use JavaScript to swap the initial colors with an alternate set of values:

[data-theme="dark"] {
  --theme-color-primary: #ffc9a2;
  --theme-color-secondary: #d09255;
  --theme-color-tertiary: #d09255;
  --text-color-primary: #fff;
  --text-color-secondary: var(--color-light);
  --text-color-tertiary: var(--color-gray-lighter);
  --body-bg: var(--color-dark);
  --focus-border-color: #35d700af;
}

JavaScript:

const toggleColorTheme = () => {
  if (html.dataset.theme === 'light') {
    document.documentElement.setAttribute('data-theme', 'dark')
    localStorage.theme = 'dark'
  } else {
    document.documentElement.setAttribute('data-theme', 'light')
    localStorage.theme = 'light'
  }
}

toggleColorTheme()

← Previous: Installation

Next: Integration →