# How to Use Font Awesome 7's Icon Transformation API: Size, Position, Rotate, and Flip

> Master Font Awesome 7's icon transformation API. Learn to scale, position, rotate, and flip icons easily using the data fa transform attribute for dynamic web designs.

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

---

**Font Awesome 7 lets you modify any icon on-the-fly using the `data-fa-transform` HTML attribute, which accepts space-separated commands for scaling, translation, rotation, and flipping.**

The Font Awesome 7 icon transformation API provides a declarative way to adjust icon appearance directly in your markup without custom CSS. By leveraging the `data-fa-transform` attribute, you can dynamically resize, reposition, rotate, and flip icons using a simple command syntax parsed by the core JavaScript engine.

## Understanding the Font Awesome 7 Transformation Syntax

The transformation API recognizes specific command patterns that map to CSS transform operations. Each command follows a consistent naming convention and accepts numeric values where applicable.

### Available Transformation Commands

- **`grow-N`** – Increases icon size by *N* units (16 units = 1em)
- **`shrink-N`** – Decreases icon size by *N* units
- **`left-N`** – Translates icon *N* units to the left
- **`right-N`** – Translates icon *N* units to the right
- **`up-N`** – Translates icon *N* units upward
- **`down-N`** – Translates icon *N* units downward
- **`rotate-N`** – Rotates icon *N* degrees clockwise
- **`flip-h`** – Mirrors icon horizontally
- **`flip-v`** – Mirrors icon vertically

## How the Transformation API Works Under the Hood

Font Awesome 7 processes transformations through a dedicated parsing pipeline in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js). Understanding this architecture helps debug complex transformation chains.

### Parsing the Transform String

The `parseTransformString` function (lines 3392–3400 in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js)) tokenizes the `data-fa-transform` attribute value. It uses regular expressions to identify valid command patterns and converts them into an internal transform object:

```javascript
{
  size: 16,        // Base size (16 = 1em)
  x: 0,            // Horizontal translation in units
  y: 0,            // Vertical translation in units
  rotate: 0,       // Rotation in degrees
  flipX: false,    // Horizontal flip state
  flipY: false     // Vertical flip state
}

```

### Building the Transform Object

The `parseNodeAttributes` function (lines 3454–3459) reads the HTML attribute and populates the transform metadata. It validates numeric ranges and ensures flip commands toggle boolean flags appropriately.

### Applying SVG Transforms

When rendering SVG output, `transformForSvg` (lines 3420–3439) constructs three distinct transform layers:

1. **Outer container translation** – Centers the icon coordinate system: `translate(containerWidth/2, 256)`
2. **Inner group transformation** – Applies scaling (size adjustments and flips), translation, and rotation
3. **Path recentering** – Offsets the glyph to maintain visual center: `translate(-iconWidth/2, -256)`

### CSS Transform Generation

For CSS-based rendering, `transformForCss` (lines 3429–3450) generates a CSS `transform` property value that mirrors the SVG matrix calculations, ensuring consistent appearance across rendering modes.

## Practical Code Examples

### Basic Size Adjustments

Increase an icon's size by 4 units (approximately 0.25em per unit):

```html
<i class="fa-solid fa-star" data-fa-transform="grow-4"></i>

```

Decrease size for a smaller icon:

```html
<i class="fa-solid fa-search" data-fa-transform="shrink-2"></i>

```

### Positioning Icons

Fine-tune icon placement without affecting layout flow:

```html
<i class="fa-solid fa-arrow-right" data-fa-transform="right-2 down-1"></i>

```

Nudge icons to align with text baselines:

```html
<i class="fa-solid fa-check" data-fa-transform="up-1"></i>

```

### Rotation and Flipping

Rotate icons clockwise by degrees:

```html
<i class="fa-solid fa-arrow-up" data-fa-transform="rotate-45"></i>

```

Mirror icons horizontally or vertically:

```html
<i class="fa-solid fa-flag" data-fa-transform="flip-h"></i>

```

Combine flipping and rotation for complex orientations:

```html
<i class="fa-solid fa-heart" data-fa-transform="shrink-2 flip-h flip-v"></i>

```

### Combining Multiple Transformations

Chain commands in a single attribute for complex modifications:

```html
<i class="fa-solid fa-bolt" data-fa-transform="grow-3 left-1 up-2 rotate-30 flip-h"></i>

```

Order matters: transformations apply sequentially from left to right as parsed by `parseTransformString`.

### Programmatic API Usage

For dynamic icon generation in JavaScript, pass a transform object to the `icon` helper:

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

library.add(faCoffee);

const html = icon({
  prefix: 'fas',
  iconName: 'coffee',
  transform: { 
    size: 18,    // Equivalent to grow-2 (base 16 + 2)
    x: 3,        // Equivalent to right-3
    y: 0, 
    rotate: 15, 
    flipX: false, 
    flipY: false 
  }
}).html[0];

document.body.insertAdjacentHTML('beforeend', html);

```

## Key Implementation Files

Understanding the source architecture helps when debugging transformation issues or contributing to the project:

| File | Purpose |
|------|---------|
| [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) | Core engine containing `parseTransformString`, `transformForSvg`, and `transformForCss` implementations |
| `js-packages/@fortawesome/fontawesome-svg-core/index.js` | NPM package entry point exporting the SVG core functionality |
| [`scss/_variables.scss`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_variables.scss) | Defines `UNITS_IN_GRID` (16 units = 1em), the base unit for all size calculations |
| `docs/Using Icons.md` | End-user documentation for the `data-fa-transform` syntax |

## Summary

- **Font Awesome 7's icon transformation API** uses the `data-fa-transform` HTML attribute to modify icon appearance declaratively.
- **Available commands** include `grow`, `shrink`, `left`, `right`, `up`, `down`, `rotate`, `flip-h`, and `flip-v`, parsed by `parseTransformString` in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js).
- **Internal representation** converts commands to a transform object with `size`, `x`, `y`, `rotate`, `flipX`, and `flipY` properties.
- **Rendering pipeline** applies transformations via `transformForSvg` for SVG output and `transformForCss` for CSS-based rendering.
- **JavaScript API** allows programmatic transformation by passing a transform object to the `icon()` helper function.

## Frequently Asked Questions

### What is the default base unit for grow and shrink commands?

The default base unit is **16 units per em**, defined by the `UNITS_IN_GRID` constant in [`scss/_variables.scss`](https://github.com/FortAwesome/Font-Awesome/blob/main/scss/_variables.scss). When you specify `grow-4`, you increase the icon size by 4/16 em (0.25 em). The `parseTransformString` function in [`js/fontawesome.js`](https://github.com/FortAwesome/Font-Awesome/blob/main/js/fontawesome.js) processes these values relative to the base 16-unit grid.

### Can I combine multiple transformations in a single data-fa-transform attribute?

Yes, you can chain multiple commands in a single space-separated list. For example, `data-fa-transform="grow-2 right-3 rotate-45"` applies all three transformations sequentially. The `parseTransformString` function parses these commands from left to right, building a cumulative transform object that `transformForSvg` or `transformForCss` then renders.

### How do I rotate an icon counter-clockwise?

Use negative values with the `rotate` command. For example, `data-fa-transform="rotate--45"` rotates the icon 45 degrees counter-clockwise. The parser accepts negative integers, and the `transformForSvg` function applies the rotation value directly to the SVG transform matrix, where negative degrees produce counter-clockwise rotation.

### What is the difference between flip and rotate transformations?

**Flip operations** (`flip-h` and `flip-v`) mirror the icon across the horizontal or vertical axis by applying a negative scale factor in the respective dimension, implemented in `transformForSvg` as `scale(-1, 1)` or `scale(1, -1)`. **Rotate operations** (`rotate-N`) perform a circular rotation around the center point using a rotation matrix. While `flip-h` followed by `flip-v` produces a 180-degree rotation visually, the underlying transform matrices differ, and flip operations preserve the icon's orientation relative to its mirrored axis rather than rotating the coordinate system.