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

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. Understanding this architecture helps debug complex transformation chains.

Parsing the Transform String

The parseTransformString function (lines 3392–3400 in 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:

{
  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):

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

Decrease size for a smaller icon:

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

Positioning Icons

Fine-tune icon placement without affecting layout flow:

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

Nudge icons to align with text baselines:

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

Rotation and Flipping

Rotate icons clockwise by degrees:

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

Mirror icons horizontally or vertically:

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

Combine flipping and rotation for complex orientations:

<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:

<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:

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	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	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.
• 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. When you specify grow-4, you increase the icon size by 4/16 em (0.25 em). The parseTransformString function in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}