# Font Awesome 7 Layering System: How to Stack Icons with fa-layers

> Master Font Awesome 7 layering with fa-layers to stack icons, counters, and text. Learn to create complex SVG elements effortlessly and enhance your web designs. Get started now.

- Repository: [Font Awesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome)
- Tags: how-to-guide
- Published: 2026-03-01

---

**Font Awesome 7 implements a flexible layering system through three core mixins—`Layers`, `LayersCounter`, and `LayersText`—that generate abstract DOM structures converted to SVG elements, enabling you to stack multiple icons, counters, and text within a single visual container.**

The **Font Awesome 7 layering system** (often referenced by the `fa-layers` class) moves beyond simple icon replacement to provide a composable graphics API. Located in the `@fortawesome/fontawesome-svg-core` package, this system uses JavaScript mixins to construct abstract element trees that the core rendering engine later materializes as properly positioned SVG nodes.

## Core Architecture: Layers, LayersCounter, and LayersText Mixins

The layering functionality is implemented in `js-packages/@fortawesome/fontawesome-svg-core/index.js` through three primary mixins that handle different types of layered content.

### The Layers Mixin

The **`Layers`** mixin creates the foundational container for any stack. It generates a `<span class="fa-layers …">` element and assembles abstract children supplied by the user.

According to the Font Awesome 7 source code, the implementation (lines 2925–2945) establishes a **relative positioning context** for the container while setting each child SVG to **absolute positioning** to fill the container completely. This ensures that stacked icons occupy the same visual space without affecting document flow.

### The LayersCounter Mixin

The **`LayersCounter`** mixin builds small notification badges (e.g., unread counts). It produces a `<span>` with the `fa-layers-counter` class and applies any custom classes, styles, or attributes passed by the developer.

The implementation (lines 2958–2970) relies on the helper function **`makeLayersCounterAbstract`** (lines 2286–2296) to assemble the final abstract representation with proper attributes and inline styles before the core renderer processes it.

### The LayersText Mixin

The **`LayersText`** mixin renders arbitrary text centered over the icon stack. It outputs a `<span>` with the `fa-layers-text` class and merges optional transform, style, class, or attribute options.

Found at lines 2994–3015 in [`index.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/index.js), this mixin utilizes **`makeLayersTextAbstract`** (lines 2860–2872) to construct the abstract DOM structure. This helper ensures that text elements receive the correct positioning data before SVG conversion.

## CSS Positioning and Styling Rules

The visual stacking behavior depends on CSS rules defined in `js-packages/@fortawesome/fontawesome-svg-core/styles.css`. These rules establish the coordinate system that the JavaScript mixins manipulate.

- **`.fa-layers`** – Creates a relative inline-block of size `1em`, establishing the stacking context for all child elements (lines 84–90).

- **`.fa-layers .svg-inline--fa`** – Absolutely positions each child SVG to fill the container completely, ensuring icons overlap perfectly rather than flowing sequentially (lines 92–98).

- **`.fa-layers-text`** – Centers text using a transform that translates the element to the middle of the container, allowing labels to sit precisely over icon stacks (lines 99–104).

- **`.fa-layers-counter`** – Positions and scales notification badges, defaulting to the top-right corner of the stacking context (lines 106–121).

## Implementation: HTML Syntax vs. JavaScript API

Font Awesome 7 exposes the layering system through both declarative HTML classes and an imperative JavaScript API.

### HTML Markup with fa-layers Classes

For static content, use the `fa-layers` class with child elements bearing `fa-layers-counter` or `fa-layers-text` classes. The `data-fa-transform` attribute applies positioning transforms without custom CSS.

```html
<span class="fa-layers fa-fw">
  <i class="fa-solid fa-square"></i>
  <i class="fa-solid fa-camera" data-fa-transform="shrink-6"></i>

  <!-- Counter badge -->
  <span class="fa-layers-counter" data-fa-counter="5"></span>

  <!-- Centered text -->
  <span class="fa-layers-text" data-fa-transform="rotate-45">
    NEW
  </span>
</span>

```

### Programmatic Layer Construction

For dynamic applications, import the `dom` object from `@fortawesome/fontawesome-svg-core` to build layers programmatically. This approach uses the `Layers`, `LayersCounter`, and `LayersText` mixins internally.

```javascript
import { library, dom } from '@fortawesome/fontawesome-svg-core';
import { faSquare, faCamera } from '@fortawesome/free-solid-svg-icons';

library.add(faSquare, faCamera);

// Create a layer container
const layer = dom.layers()
  .layer([
    dom.icon({ prefix: 'fas', iconName: 'square' }),
    dom.icon({ prefix: 'fas', iconName: 'camera', transform: { shrink: 6 } })
  ]);

// Add a counter badge
layer.counter('5');

// Add centered text with rotation
layer.text('NEW', { transform: { rotate: 45 } });

// Append to the document
document.body.appendChild(layer.node);

```

## Summary

- **Font Awesome 7** implements icon stacking through the `fa-layers` system, composed of three core mixins: `Layers`, `LayersCounter`, and `LayersText`.
- The mixins reside in `js-packages/@fortawesome/fontawesome-svg-core/index.js` and generate abstract DOM structures processed by the rendering engine.
- Helper functions `makeLayersCounterAbstract` and `makeLayersTextAbstract` construct the final element representations with proper attributes and styles.
- CSS rules in [`styles.css`](https://github.com/FortAwesome/Font-Awesome/blob/main/styles.css) establish the stacking context via relative positioning on `.fa-layers` and absolute positioning on child SVGs.
- Developers can implement layers declaratively using HTML classes and `data-fa-transform` attributes, or programmatically via the JavaScript `dom.layers()` API.

## Frequently Asked Questions

### How do I position a counter badge in a different corner?

By default, the `.fa-layers-counter` class positions badges in the top-right corner via CSS. To relocate the badge, override the positioning properties in your stylesheet or use the `data-fa-transform` attribute with directional keywords like `down-4` or `left-4` to shift the counter relative to the container center.

### Can I use fa-layers with the CSS/Font-based version of Font Awesome?

No. The `fa-layers` system requires the **SVG with JavaScript** implementation found in `@fortawesome/fontawesome-svg-core`. The CSS/Font version renders icons as font glyphs, which cannot be stacked with the absolute positioning and abstract DOM manipulation that the layering mixins require.

### What is the difference between data-fa-transform and direct CSS transforms?

The `data-fa-transform` attribute accepts Font Awesome-specific keywords like `shrink-6`, `rotate-45`, or `up-2` that the core library parses into precise SVG transform matrices. Direct CSS transforms apply standard CSS properties to the rendered element. Using `data-fa-transform` ensures that positioning calculations occur during the abstract-to-SVG conversion phase, maintaining proper alignment within the stacking context.

### How do I access the layers API in a React or Vue application?

Import the `dom` object from `@fortawesome/fontawesome-svg-core` and invoke `dom.layers()` within a `useEffect` (React) or `mounted` (Vue) lifecycle hook to construct the layer node. Append the resulting `layer.node` to a ref’s current element. Alternatively, use the official `react-fontawesome` or `vue-fontawesome` packages, which expose a `Layers` component that wraps these imperative API calls into declarative component syntax.