Plugins

The simple plugin API allows you to bring additional capabilities to Hacss such as variables, custom shorthand properties, or even a custom implementation of a native property.

Plugins affect how declarations are rendered in the generated CSS output. Each plugin is, essentially, a plain JavaScript function parameterized by a map of current declarations that returns a new map of declarations. For example:

// Argument: original declarations
{
  "padding-x": "20px",
  "padding-y": "12px"
}

// Return value: modified declarations
{
  "padding-left": "20px",
  "padding-right": "20px",
  "padding-top": "12px",
  "padding-bottom": "12px"
}

Architecture

Plugins are specified in the configuration object's plugins array, where they are run in the reverse of the specified order; e.g. the last plugin specified is invoked first, while the plugin at index 0 is reached last. The return value of each plugin is provided as the argument to the next.

A plugin must take either of two specific forms:

  1. A function, parameterized by a declaration object, that returns a new declaration object
  2. A tuple (2-item array), where the first item is a function as described above and the second item is a string array containing any additional property names that the plugin knows how to handle

Use the first form where you are just changing values or redefining existing CSS properties. Use the second when you are creating custom properties.

Examples

const boxShadowOutlinePlugin = decls => {
  if ("outline" in decls) {
    const outlineValue = decls["outline"];
    decls["box-shadow"] = /* use box-shadow to make a fancy outline */"";
    delete decls["outline"];
  }
  return decls;
};

const horizontalPaddingPlugin = [
  decls => {
    if ("padding-x" in decls) {
      decls["padding-left"] = decls["padding-right"] = decls["padding-x"];
      delete decls["padding-x"];
    }
    return decls;
  },
  ["padding-x"],
];

Variables Plugin

The Variables plugin allows you to use variables in declaration values.

Installation

NPM:

npm install -D @hacss/plugin-variables

Hacss configuration:

const variables = require("@hacss/plugin-variables");

Basic Usage

Hacss configuration:

module.exports = {
  plugins: [
    variables({
      blue500: "#009",
      "sans-serif": "'Inter', sans-serif",
    }),
  ],
};

Markup:

<button class="font-family:$sans-serif; color:$blue500;">Button Text</button>

Indexed Variables

Indexed variables are resolved to a different value depending on the property to which they are applied.

Hacss configuration:

module.exports = {
  plugins: [
    variables({
      "font-size": {
        small: "12px",
      },
      "border-radius": {
        small: "2px",
      },
    }),
  ],
};

Markup:

<button class="font-size:$small; border-radius:$small;">Button Text</button>

Pipes

Pipes introduce a minimal amount of programmability so that variables can be modified in certain contexts.

Hacss configuration:

module.exports = {
  plugins: [
    variables({
      red500: "#400",
      "url-encode": encodeURIComponent,
    }),
  ],
};

Markup:

<div class="color:white; background:url('dynbg.gif?color=$(red500|url-encode)');">
  Hello World
</div>

Expand Plugin

The Expand plugin allows you to expand custom shorthand declarations.

Installation

NPM:

npm install -D @hacss/plugin-expand

Hacss configuration:

const expand = require("@hacss/plugin-expand");

Usage

Hacss configuration:

module.exports = {
  plugins: [
    expand({
      "padding-x": ["padding-left", "padding-right"],
      "padding-y": ["padding-top", "padding-bottom"],
    }),
  ],
};

Markup:

<button class="padding-x:20px; padding-y:16px;">Button Text</button>

Copy Plugin

The Copy plugin allows you to copy the value of a declaration to another declaration.

Installation

NPM:

npm install -D @hacss/plugin-copy

Hacss configuration:

const copy = require("@hacss/plugin-copy");

Usage

Hacss configuration:

module.exports = {
  plugins: [
    copy({
      "appearance": ["-webkit-appearance", "-moz-appearance"],
    }),
  ],
};

Markup:

<input type="checkbox" class="appearance:none;" />

Delete Plugin

The Delete plugin allows you to remove declarations by property name.

Installation

NPM:

npm install -D @hacss/plugin-delete

Hacss configuration:

const del = require("@hacss/plugin-delete");

Usage

Hacss configuration:

module.exports = {
  plugins: [
    del(["text-stroke"]),
  ],
};

Markup:

<span class="text-stroke:1px__red;">
  Just kidding: No text stroke to see here
</span>
Hacss
Overview Getting Started Guides Basement GitHub