globalLayer

Creates a globally scoped layer.

🚧  Ensure your target browsers support layers. Vanilla Extract supports the layers syntax but does not polyfill the feature in unsupported browsers.

import { globalLayer } from '@vanilla-extract/css';

globalLayer('reset');

@layer reset;

Useful for orchestrating the order of layers within the stylesheet, for example:

import { globalLayer } from '@vanilla-extract/css';

globalLayer('reset');
globalLayer('framework');
globalLayer('app');

@layer reset;
@layer framework;
@layer app;

Nesting layers

To facilitate organisation of styles, layer nesting is supported by providing a parent layer name via the options object. This will generate the shorthand syntax, i.e. parent.child, while also making the relationship between layers explicit.

import { globalLayer } from '@vanilla-extract/css';

globalLayer('reset');
globalLayer('framework');
globalLayer({ parent: 'framework' }, 'typography');

@layer reset;
@layer framework;
@layer framework.typography;

Assigning styles

Styles can be assigned to a layer by name, using the @layer key in the style object.

In this example, we first import the layers.css.ts stylesheet, setting up the order of the layers, then create a style within the reset layer.

import { style } from '@vanilla-extract/css';
import './layers.css.ts';

export const noMargin = style({
  '@layer': {
    reset: {
      margin: 0
    }
  }
});

@layer reset;
@layer reset {
  .reset_noMargin__1m3l8q90 {
    margin: 0;
  }
}

Best practice would be to expose the layer references from the layers.css.ts stylesheet, and use those when creating styles.

import { style } from '@vanilla-extract/css';
import { reset } from './layers.css.ts';

export const noMargin = style({
  '@layer': {
    [reset]: {
      margin: 0
    }
  }
});

@layer reset;
@layer reset {
  .reset_noMargin__1m3l8q90 {
    margin: 0;
  }
}

This is particularly useful when using the nested layers feature, as the parent and child names are computed.

In our example, the name of the typography layer becomes framework.typography:

import { style } from '@vanilla-extract/css';
import { typography } from './layers.css.ts';

export const standard = style({
  '@layer': {
    [typography]: {
      fontSize: '1rem'
    }
  }
});

@layer framework.typography;
@layer framework.typography {
  .text_standard__fih47p0 {
    font-size: 1rem;
  }
}

Layer merging

In order to generate the smallest possible CSS output, Vanilla Extract will merge styles that are assigned to the same layer within the same file, if it can be done without impacting the precedence of the rules.

Notice in this example, while the themedHeading style is created before the the heading style, it appears later in the stylesheet. This is due to it being assigned to the theme layer — which is declared after the base layer.

import { style, globalLayer } from '@vanilla-extract/css';

const base = globalLayer('base');
const theme = globalLayer('theme');

const text = style({
  '@layer': {
    [base]: {
      fontSize: '1rem'
    }
  }
});
const themedHeading = style({
  '@layer': {
    [theme]: {
      color: 'rebeccapurple'
    }
  }
});
const heading = style({
  '@layer': {
    [base]: {
      fontSize: '2.4rem'
    }
  }
});

@layer base;
@layer theme;
@layer base {
  .typography_text__94ldqt0 {
    font-size: 1rem;
  }
  .typography_heading__94ldqt2 {
    font-size: 2.4rem;
  }
}
@layer theme {
  .typography_themedHeading__94ldqt1 {
    color: rebeccapurple;
  }
}