Griffel Documentation

Griffel is a CSS-in-JS library designed with near-zero runtime and SSR support. Key features include:

• Zero config start: Supports both runtime and build-time implementations.
• Performance: Optional build-time transforms (e.g., via Webpack loader) are available to improve performance.
• Type-safety: Styles are type-safe via csstype.
• Atomic CSS: Uses Atomic CSS to maximize style reuse and prevent CSS specificity issues.
• CSS Extraction: Experimental CSS extraction is available via a Webpack plugin.
• Debugging: Supports the Griffel DevTools browser extension for debugging styles.

Griffel uses rtl-css-js to automatically flip properties and values in Right-To-Left text directions, controlled by the TextDirectionProvider.

• Automatic flipping: Properties like paddingLeft will automatically become paddingRight in RTL mode.
• Preventing flips: To prevent a specific rule from being flipped, add the /* @noflip */ comment to the property value.

import { makeStyles } from '@griffel/react';

// This will flip in RTL
const useFlipping = makeStyles({
  root: {
    paddingLeft: '10px',
  },
});

// This will NOT flip in RTL
const useNoFlip = makeStyles({
  root: {
    paddingLeft: '10px /* @noflip */',
  },
});

import { makeStyles } from '@griffel/react';

const useClasses = makeStyles({
  root: {
    paddingLeft: '10px',
  },
});

// ...

const useNoFlip = makeStyles({
  root: {
    paddingLeft: '10px /* @noflip */',
  },
});

You can use the & character to reference the parent selector. This is useful for targeting child elements or applying styles based on the parent's state/class.

Note: Because Griffel uses Atomic CSS, nesting more selectors increases the number of generated styles. Use with caution.

import { makeStyles } from '@griffel/react';

const useClasses = makeStyles({
  root: {
    '& .foo': { color: 'green' },
    '&.bar': { color: 'red' },
  },
});

Because Griffel's AOT (Ahead-of-Time) compilation cannot create new rules at runtime, style overrides are achieved by merging existing atomic classes.

When multiple classes targeting the same property are applied to an element, Griffel ensures that only one set of properties is applied. The rule is that the last defined property-value pair wins. To ensure correct behavior when applying multiple sets of styles, use the mergeClasses API.

Griffel uses an Atomic CSS approach where every property-value pair is written as a single, reusable CSS rule. This contrasts with monolithic classes that group multiple properties into one class.

Benefits:

• Reusability: CSS rules are reused across different components, reducing the total amount of defined CSS.
• Reduced CSS Size: As the application grows, the amount of new CSS rules scales more slowly than the number of components.

Trade-offs:

• Larger HTML Markup: Every CSS rule adds a class to the HTML element, increasing the number of classes per element.
• Recalculation Performance: Browsers experience linear performance degradation as the number of classes on an element increases. While rare, exceeding 100 classes (often via heavy use of nested selectors) can impact performance. It is recommended to avoid excessive nesting to keep class counts low.

In CSS, pseudo-classes like :hover and :active have equal specificity, and their behavior is determined by the order of appearance in the cascade. Since atomic classes are inserted into the DOM based on usage/definition, the order can become non-deterministic.

To ensure deterministic results, Griffel automatically orders common pseudo-classes in the following sequence:

1. :link
2. :visited
3. :focus-within
4. :focus
5. :focus-visible
6. :hover
7. :active

The last defined pseudo-class in this order will win if multiple states apply simultaneously.

Griffel generates atomic class names by hashing style declarations (e.g., ___1t65jhk_nkb4zh0). Because these hashes are implementation details that can change during Griffel upgrades or unrelated style changes, they often cause brittle snapshots.

This serializer removes class names generated by both makeStyles() and makeResetStyles(), leaving only the markup you wrote. Any class names not generated by Griffel are preserved.

When inspecting or updating CSS snapshots, be aware of two behaviors:

1. Prettier: Snapshots are formatted using Prettier.
2. Redaction: Class names for rules containing url() are redacted. This is because @griffel/transform hashes the resolved absolute asset path, which varies depending on the machine running the test.

The @griffel/webpack-extraction-plugin is a Webpack 5 plugin designed for applications to perform CSS extraction for @griffel/react.

Prerequisites:

• You must configure @griffel/webpack-loader first. This plugin relies on assets transformed by that loader.

Key Behaviors:

• It transforms code to remove generated CSS from JavaScript files and creates separate CSS assets.
• Limitation: Currently, all CSS rules are extracted to a single CSS file. Webpack code splitting for extracted CSS is not supported at this time.