Transforms

Purpose and Scope

This page is a focused reference for Tailwind CSS transform utilities: the classes that set the CSS transform property directly, the transform-origin helpers that define the pivot point for transforms, and the transform-style helpers that control whether children participate in 3D space. It also orients readers to the package and runtime entry points that make these utilities available in installed projects, command-line builds, Node-powered integrations, and browser/CDN workflows. The official utility surface includes transform-gpu, transform-cpu, transform-none, arbitrary transform values, origin keywords such as origin-top-left, and 3D composition classes such as transform-3d.

Tailwind treats these utilities as class candidates that are compiled into CSS only when they are used. In day-to-day authoring, that means a class like rotate-45, scale-150, translate-z-12, origin-bottom, or transform-3d is written directly in markup and then discovered by the compiler path used by the chosen integration. The core package exposes the stylesheet and TypeScript entry point for tailwindcss, while the surrounding packages wire the same compiler into the browser runtime, CLI, and Node API. Sources: packages/tailwindcss/src/index.ts, packages/tailwindcss/package.json, packages/@tailwindcss-browser/src/index.ts, packages/@tailwindcss-cli/src/index.ts, packages/@tailwindcss-node/src/index.ts

Relevant Source Files

• packages/tailwindcss/src/index.ts — Core compiler entry point that imports the design system, utility creation, candidate compilation, directives, variants, theme handling, AST helpers, and source-map support used by integrations.
• packages/tailwindcss/package.json — Defines the public tailwindcss package metadata, version, exports for the main CSS entry files, compatibility helpers, plugin entry points, and published distribution files.
• package.json — Defines repository-level scripts such as build, dev, test, test:integrations, and test:ui, which are the operational paths for validating utility behavior across packages.
• packages/@tailwindcss-browser/src/index.ts — Implements the browser runtime used by Play CDN-style workflows, including stylesheet discovery, compiler creation, virtual Tailwind asset loading, class tracking, and queued builds.
• packages/@tailwindcss-cli/src/index.ts — Provides the tailwindcss executable entry point, command dispatch, help behavior, build command wiring, and canonicalize command routing.
• packages/@tailwindcss-node/src/index.ts — Re-exports Node integration APIs for compile, optimization, instrumentation, path normalization, source maps, and environment helpers, and registers module-loading hooks when available.

Utility Families

The transform family starts with utilities that control the complete transform declaration. transform-none removes transforms from an element, which is useful when a responsive or state variant should undo earlier composition such as skew-y-3 md:transform-none. transform-gpu forces hardware acceleration by including translateZ(0) before Tailwind’s internal rotate and skew variables, while transform-cpu removes that GPU hint and uses the variable-driven rotate and skew sequence. The official docs also define transform-[<value>] for a complete arbitrary transform and transform-(<custom-property>) as a shorthand for a CSS variable-backed transform value.

Transform-origin utilities define the point around which rotation, scaling, and skewing occur. The documented keyword classes are origin-center, origin-top, origin-top-right, origin-right, origin-bottom-right, origin-bottom, origin-bottom-left, origin-left, and origin-top-left. These map directly to transform-origin values like center, top right, or bottom left. The custom forms follow Tailwind’s arbitrary-value conventions: origin-[33%_75%] emits a custom origin value, and origin-(--my-transform-origin) expands the custom property shorthand into a var() expression. Use origin utilities when the same visual transform should pivot from a different edge, corner, or coordinate.

Transform-style utilities are the bridge from normal two-dimensional composition into nested 3D scenes. The official docs define transform-3d as transform-style: preserve-3d and transform-flat as transform-style: flat. Without preserving 3D space on the parent, transformed children are flattened into the element’s plane even if the children use classes such as translate-z-12, rotate-x-90, or rotate-y-90. In practical components, place transform-3d on the parent container and then use translate, rotate, scale, perspective, and origin utilities on children to construct the visible arrangement.

System-to-Code Mapping

The utilities themselves are authored through Tailwind’s CSS-first compiler model rather than through a separate runtime API in each integration package. The core entry point imports the Theme abstraction, buildDesignSystem, createCssUtility, compileCandidates, variant substitution, @apply handling, imports, CSS functions, AST helpers, and source-map creation. That combination shows the high-level flow: parse CSS and Tailwind directives, construct a design system from theme data, compile class candidates into CSS utilities, apply variants, optimize the AST, and serialize CSS for the caller. Sources: packages/tailwindcss/src/index.ts

Package exports determine how transform utilities enter user projects. The tailwindcss package exposes the main CSS entry, index.css, preflight.css, theme.css, and utilities.css, alongside TypeScript and CommonJS/ESM package entry points. For transform utilities, utilities.css is the key public stylesheet surface because it is the layer that ultimately contains generated utility rules. The package also exposes compatibility helpers such as colors, default theme, flatten color palette, and the plugin entry point, but the transform workflow for most users begins with importing tailwindcss or one of its CSS entry files. Sources: packages/tailwindcss/package.json

Different runtimes call into the same conceptual compiler pipeline. The CLI entry point accepts the root tailwindcss command, a build subcommand, and a canonicalize command, so a project can produce transform CSS from an input stylesheet without depending on a framework integration. The Node package re-exports compile and optimization APIs for build tools that need programmatic control. The browser runtime creates a compiler in the page, injects a default @import "tailwindcss" when the user has not supplied imports, loads virtual Tailwind assets, tracks classes seen so far, and queues builds to avoid concurrent compilation. Sources: packages/@tailwindcss-cli/src/index.ts, packages/@tailwindcss-node/src/index.ts, packages/@tailwindcss-browser/src/index.ts

Authoring Patterns

A common pattern is to compose several independent transform utilities instead of writing one large custom transform declaration. For example, an image can combine origin-top-left rotate-12 scale-105, while an interactive card might use hover:-translate-y-1 hover:scale-105 transition-transform. Tailwind’s class model keeps each visual decision local and variant-friendly: the origin can be responsive, the scale can be hover-only, and the transform reset can apply at a breakpoint. When the desired transform cannot be represented by the standard translate, rotate, scale, or skew utilities, use transform-[matrix(1,2,3,4,5,6)] or the custom-property shorthand.

For 3D effects, think in terms of parent context and child placement. The parent decides whether its children are flattened or preserved in 3D space using transform-flat or transform-3d. Children then use axis-aware transforms such as X/Y/Z translation and X/Y rotation, plus normal background, sizing, and positioning utilities. The transform-style docs demonstrate a cube-like layout where children use translate-z-12, -translate-z-12, translate-x-12, rotate-y-90, and rotate-x-90; the important rule is that those child transforms only behave as a 3D arrangement when the parent preserves 3D space.

Variants work with transform utilities in the same way they work with other Tailwind utilities. A breakpoint prefix such as md:origin-top changes the transform origin at medium screens and above, while md:transform-flat can flatten a 3D composition at a larger layout. State variants such as hover:, focus:, or group/peer variants can conditionally apply translate, rotate, scale, or reset utilities. Because the core compiler imports variant handling and candidate compilation together, integrations can ask for the same class strings and receive CSS that reflects both the transform utility and its variant context. Sources: packages/tailwindcss/src/index.ts

Compact Reference

A minimal installed build path can use the CLI package and the core stylesheet import. The CLI entry point routes tailwindcss and tailwindcss build into the build command, while the core package exposes index.css and the split theme, preflight, and utilities CSS files. A local workflow can therefore author transform classes in templates, include Tailwind from input CSS, and invoke a build command that produces only the utilities discovered for the project. Repository scripts then provide the broader contributor workflow for building and testing those packages together. Sources: package.json, packages/tailwindcss/package.json, packages/@tailwindcss-cli/src/index.ts

@import "tailwindcss";

<div class="origin-top-left rotate-12 scale-105 md:origin-center md:transform-none">
  <!-- content -->
</div>

Execution Flow Across Runtimes

In a browser/CDN workflow, Tailwind runs directly in the page. The browser package looks for <style> elements with the type used for Tailwind input CSS, observes those stylesheets, concatenates their contents, injects @import "tailwindcss" when no import is present, and creates a compiler with virtual assets for the core Tailwind CSS files. It maintains a set of seen classes so subsequent builds can pass only new candidates to the compiler, and it serializes build work through a promise queue. That runtime shape is especially relevant for transform examples because editing markup can immediately produce utilities such as transform-3d, origin-bottom, or transform-gpu. Sources: packages/@tailwindcss-browser/src/index.ts

In Node-backed integrations, the @tailwindcss/node entry point is the public package surface for compile, optimization, source maps, instrumentation, normalized paths, and environment helpers. It also handles module-loading cache behavior by registering resolver hooks when the current runtime supports them, with a Bun-specific branch because Bun populates require.cache for ESM modules. Transform utilities do not require a special Node API; they benefit from the same programmatic compiler surface as every other utility family. This is why build-tool integrations can expose Tailwind’s transform classes without reimplementing transform-specific logic. Sources: packages/@tailwindcss-node/src/index.ts

Testing and Next Steps

When validating transform behavior, test the authored class string in the same runtime the application uses. For a project using the CLI, verify the input stylesheet imports Tailwind and run the build command. For a browser playground or CDN-style reproduction, check that the Tailwind style tag is present and that class changes are observed. For integration or package work, use the repository scripts: pnpm run build, pnpm run test, pnpm run test:integrations, and pnpm run test:ui are declared at the root and cover the TypeScript, Rust, Vitest, integration, and browser-facing test paths. Sources: package.json

Next, read the pages for transitions-and-animation when transforms need motion, responsive-design when transform utilities change by breakpoint, hover-focus-and-other-states when transforms respond to interaction, and tailwindcss-package-api or cli-reference when you need to understand the compiler or command-line entry points behind generated CSS.