feat(react-icons): propagate headless/ API to stable (#1119)

Hotell · web-flow · commit 1132d2574fb1 · 2026-06-29T15:44:52.000+02:00
diff --git a/packages/docsite/stories/Icons/UserGuidance.mdx b/packages/docsite/stories/Icons/UserGuidance.mdx
@@ -23,7 +23,7 @@ import { Meta } from '@storybook/addon-docs/blocks';
 | **Loading**             | Bundled with JS — no flash                      | FOIT / FOUT risk during font load                           | One request per sprite group; webpack plugin can merge into a single request         |
 | **Setup**               | None (default)                                  | Webpack subsetting plugin, static assets hosting (font)     | Webpack subsetting plugin, static assets hosting (sprite), same-origin proxy for CDN |
 
-> **Note:** A **headless** rendering mode (vanilla CSS, no Griffel runtime) is available as an alpha opt-in via `/headless/*` imports (e.g. `@fluentui/react-icons/headless/svg/access-time`). With CSS extraction it reduces JS bundle sizes significantly — up to −70% for font icons, −56% for SVG sprites, −14% for inline SVG. This table will be updated once the headless API ships in stable.
+> **Note:** A **headless** rendering mode (vanilla CSS, no Griffel runtime) is available via `/headless/*` imports (e.g. `@fluentui/react-icons/headless/svg/access-time`). With CSS extraction it reduces JS bundle sizes significantly — up to −70% for font icons, −56% for SVG sprites, −14% for inline SVG. See the [Headless API documentation](https://github.com/microsoft/fluentui-system-icons/blob/main/packages/react-icons/docs/headless.md) for details.
 
 ### When to use inline SVG (default)
 
diff --git a/packages/react-icons/README.md b/packages/react-icons/README.md
@@ -348,13 +348,11 @@ SVG sprites offer smaller bundles, faster renders, and zero runtime overhead.
 
 👉 **[Full documentation →](./docs/preview-features/svg-sprites.md)**
 
-## Headless API — ⚠️ Alpha
-
-> **This feature is available as an alpha prerelease only.** Install via `npm i @fluentui/react-icons@alpha`
+## Headless API
 
 A drop-in replacement for the standard API that removes the CSS-in-JS runtime — provides data-attribute selectors for styling behaviour with opt-in pre-defined vanilla CSS.
 
-👉 **[Full documentation →](./docs/preview-features/headless.md)**
+👉 **[Full documentation →](./docs/headless.md)**
 
 ## Viewing Icons
 
diff --git a/packages/react-icons/build-verify.test.js b/packages/react-icons/build-verify.test.js
@@ -2473,28 +2473,30 @@ describe('Build Verification', () => {
         'useIconState.d.ts',
         'bundleIcon.js',
         'bundleIcon.d.ts',
-        'headless.css',
+        'utils.js',
+        'utils.d.ts',
+        'styles.css',
       ];
       for (const file of expectedFiles) {
         expect(fs.existsSync(path.join(headlessDir, file))).toBe(true);
       }
 
-      // headless.css must use data-attribute selectors (the key differentiator from CSS-in-JS)
-      const css = await readFile(path.join(headlessDir, 'headless.css'), 'utf-8');
+      // styles.css must use data-attribute selectors (the key differentiator from CSS-in-JS)
+      const css = await readFile(path.join(headlessDir, 'styles.css'), 'utf-8');
       expect(css).toContain('[data-fui-icon]');
       expect(css).toContain('[data-fui-icon-rtl]');
       expect(css).toContain('[data-fui-icon-hidden]');
 
       // Font sub-infrastructure
       expect(fs.existsSync(path.join(headlessDir, 'fonts', 'createFluentFontIcon.js'))).toBe(true);
-      expect(fs.existsSync(path.join(headlessDir, 'fonts', 'headless-fonts.css'))).toBe(true);
+      expect(fs.existsSync(path.join(headlessDir, 'fonts', 'styles.css'))).toBe(true);
     });
 
     it('package.json#sideEffects include headless entries css entries', () => {
       const packageJsonPath = path.join(__dirname, 'package.json');
       const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 
-      expect(packageJson.sideEffects).toEqual(['**/headless/fonts/headless-fonts.css', '**/headless/headless.css']);
+      expect(packageJson.sideEffects).toEqual(['**/headless/fonts/styles.css', '**/headless/styles.css']);
     });
   });
 
diff --git a/packages/react-icons/bundle-size/headless-bundle.fixture.js b/packages/react-icons/bundle-size/headless-bundle.fixture.js
@@ -0,0 +1,8 @@
+import { AirplaneFilled, AirplaneRegular } from '@fluentui/react-icons/headless/svg/airplane';
+import { bundleIcon } from '@fluentui/react-icons/headless/utils';
+
+const Airplane = bundleIcon(AirplaneFilled, AirplaneRegular);
+
+console.log(Airplane);
+
+export default { name: 'Headless - Bundle Icon' };
diff --git a/packages/react-icons/bundle-size/headless-fonts.fixture.js b/packages/react-icons/bundle-size/headless-fonts.fixture.js
@@ -0,0 +1,5 @@
+import { AirplaneRegular } from '@fluentui/react-icons/headless/fonts/airplane';
+
+console.log(AirplaneRegular);
+
+export default { name: 'Headless - Single Fonts' };
diff --git a/packages/react-icons/bundle-size/headless-svg.fixture.js b/packages/react-icons/bundle-size/headless-svg.fixture.js
@@ -0,0 +1,5 @@
+import { AirplaneRegular } from '@fluentui/react-icons/headless/svg/airplane';
+
+console.log(AirplaneRegular);
+
+export default { name: 'Headless - Single SVG' };
diff --git a/packages/react-icons/docs/bundle-size-rendering-approaches-comparison.md b/packages/react-icons/docs/bundle-size-rendering-approaches-comparison.md
@@ -51,7 +51,7 @@
 
 When webpack uses `style-loader` (the default — no `MiniCssExtractPlugin`), the **headless fonts** bundle is **+1,344 B minified (+13%)** larger than the Griffel baseline. This is counter-intuitive — the headless approach was designed to remove the CSS-in-JS runtime, but in this mode it _replaces_ it with an even heavier runtime.
 
-**Root cause:** The two plain CSS imports (`headless-fonts.css`, `headless.css`) require webpack's `css-loader` + `style-loader` runtime to inject styles into the DOM at runtime. This runtime comprises ~10 extra webpack modules (style injection/removal API, `<style>` element creation, CSP nonce support, URL escaping, CSS text stringification, etc.) that collectively weigh more than Griffel's built-in runtime (hash function, `mergeClasses`, `makeStyles`, style insertion).
+**Root cause:** The two plain CSS imports (`fonts/styles.css`, `styles.css`) require webpack's `css-loader` + `style-loader` runtime to inject styles into the DOM at runtime. This runtime comprises ~10 extra webpack modules (style injection/removal API, `<style>` element creation, CSP nonce support, URL escaping, CSS text stringification, etc.) that collectively weigh more than Griffel's built-in runtime (hash function, `mergeClasses`, `makeStyles`, style insertion).
 
 **When headless _does_ win:** With CSS extraction (`MiniCssExtractPlugin`), the CSS moves into a separate `.css` file and the loader runtime is not needed — headless fonts then drop to **3.098 kB** (−69.5%). The style-loader overhead also gets amortized when an app already uses `css-loader`/`style-loader` for other CSS imports (the runtime is shared).
 
diff --git a/packages/react-icons/docs/headless.md b/packages/react-icons/docs/headless.md
@@ -1,9 +1,5 @@
 # Headless API
 
-> **⚠️ Alpha** — this feature is available as an alpha prerelease only.
->
-> Install via `npm i @fluentui/react-icons@prerelease`
-
 The Headless API is a drop-in replacement for the standard icon API that removes the CSS-in-JS runtime dependency. It provides `data-*` attribute selectors for styling behaviour with opt-in pre-defined vanilla CSS — making it suitable for any React setup, including those without a CSS-in-JS runtime.
 
 ## Benefits
@@ -16,7 +12,7 @@ The Headless API is a drop-in replacement for the standard icon API that removes
 
 ## How it works
 
-The standard API uses Griffel's `makeStyles` / `mergeClasses` to inject CSS rules at runtime. The headless API replaces this with HTML `data-*` attributes and a shipped CSS file (`headless.css`) that targets them:
+The standard API uses Griffel's `makeStyles` / `mergeClasses` to inject CSS rules at runtime. The headless API replaces this with HTML `data-*` attributes and a shipped CSS file (`styles.css`) that targets them:
 
 | Concern               | Standard (Griffel)                  | Headless (CSS)                                                             |
 | --------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
@@ -33,17 +29,17 @@ You **must** import the headless CSS file — this is the key difference from th
 **For SVG icons and SVG sprites:**
 
 ```ts
-import '@fluentui/react-icons/headless/headless.css';
+import '@fluentui/react-icons/headless/styles.css';
 ```
 
 **For font icons** (additionally):
 
 ```ts
-import '@fluentui/react-icons/headless/headless-fonts.css';
-import '@fluentui/react-icons/headless/headless.css';
+import '@fluentui/react-icons/headless/fonts/styles.css';
+import '@fluentui/react-icons/headless/styles.css';
 ```
 
-> **Note:** `headless-fonts.css` contains `@font-face` declarations with relative paths to the font files (`.woff2`, `.woff`, `.ttf`). Your bundler (webpack, Vite, esbuild) will resolve these into the dependency graph automatically, enabling font subsetting plugins to process them.
+> **Note:** `fonts/styles.css` contains `@font-face` declarations with relative paths to the font files (`.woff2`, `.woff`, `.ttf`). Your bundler (webpack, Vite, esbuild) will resolve these into the dependency graph automatically, enabling font subsetting plugins to process them.
 
 > **Tip 💡:** It's highly recommended to enable our [`react-icons-font-subsetting-webpack-plugin`](https://www.npmjs.com/package/@fluentui/react-icons-font-subsetting-webpack-plugin) to get same fonts "tree-shaking" perf boost
 
@@ -54,7 +50,7 @@ import '@fluentui/react-icons/headless/headless.css';
 Headless SVG icons are grouped by icon kind and exposed via `@fluentui/react-icons/headless/svg/{icon-group}`:
 
 ```tsx
-import '@fluentui/react-icons/headless/headless.css';
+import '@fluentui/react-icons/headless/styles.css';
 
 import {
   AccessTime20Filled,
@@ -78,7 +74,7 @@ function MyComponent() {
 Headless SVG sprites work the same way as standard SVG sprites but without Griffel:
 
 ```tsx
-import '@fluentui/react-icons/headless/headless.css';
+import '@fluentui/react-icons/headless/styles.css';
 
 import { AccessTime20Filled, AccessTime24Filled } from '@fluentui/react-icons/headless/svg-sprite/access-time';
 import { Add16Filled } from '@fluentui/react-icons/headless/svg-sprite/add';
@@ -93,15 +89,15 @@ function MyComponent() {
 }
 ```
 
-> **Same-origin requirement:** Sprite files must be served from the same origin as your application. See the [SVG Sprites same-origin section](./svg-sprites.md#same-origin-requirement) for details.
+> **Same-origin requirement:** Sprite files must be served from the same origin as your application. See the [SVG Sprites same-origin section](./preview-features/svg-sprites.md#same-origin-requirement) for details.
 
 ### Font Icons
 
-Headless font icons require both CSS files — `headless.css` for base styles and `headless-fonts.css` for `@font-face` declarations:
+Headless font icons require both CSS files — `styles.css` for base styles and `fonts/styles.css` for `@font-face` declarations:
 
 ```tsx
-import '@fluentui/react-icons/headless/headless-fonts.css';
-import '@fluentui/react-icons/headless/headless.css';
+import '@fluentui/react-icons/headless/fonts/styles.css';
+import '@fluentui/react-icons/headless/styles.css';
 
 import { Airplane20Filled, Airplane24Regular } from '@fluentui/react-icons/headless/fonts/airplane';
 
@@ -149,7 +145,7 @@ import {
 The `bundleIcon` function works identically to the standard API:
 
 ```tsx
-import '@fluentui/react-icons/headless/headless.css';
+import '@fluentui/react-icons/headless/styles.css';
 import { bundleIcon } from '@fluentui/react-icons/headless';
 import { AccessTimeFilled } from '@fluentui/react-icons/headless/svg/access-time';
 import { AccessTimeRegular } from '@fluentui/react-icons/headless/svg/access-time';
@@ -179,6 +175,6 @@ You can keep root-level barrel imports and leverage build transforms to adopt th
 
 Use `headless/svg` as the target path (or `headless/svg-sprite` for sprites, `headless/fonts` for font icons).
 
-> **Note:** You still need to manually add the CSS import (`import '@fluentui/react-icons/headless/headless.css'`) to your application entry point — build transforms only rewrite component imports.
+> **Note:** You still need to manually add the CSS import (`import '@fluentui/react-icons/headless/styles.css'`) to your application entry point — build transforms only rewrite component imports.
 
-👉 **[Build-Time Transform setup (Babel & SWC) →](../build-transforms.md)**
+👉 **[Build-Time Transform setup (Babel & SWC) →](./build-transforms.md)**
diff --git a/packages/react-icons/docs/preview-features/README.md b/packages/react-icons/docs/preview-features/README.md
@@ -7,7 +7,3 @@
 ## [Atomic API (SVG Sprites)](./svg-sprites.md)
 
 SVG sprites offer smaller bundles, faster renders, and zero runtime overhead.
-
-## [Headless API](./headless.md)
-
-A drop-in replacement for the standard API that removes the CSS-in-JS runtime — provides data-attribute selectors for styling behaviour with opt-in pre-defined vanilla CSS.
diff --git a/packages/react-icons/package.json b/packages/react-icons/package.json
@@ -1,7 +1,10 @@
 {
   "name": "@fluentui/react-icons",
   "version": "2.0.331",
-  "sideEffects": false,
+  "sideEffects": [
+    "**/headless/fonts/styles.css",
+    "**/headless/styles.css"
+  ],
   "main": "lib-cjs/index.js",
   "module": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -14,8 +17,8 @@
   "scripts": {
     "clean": "git clean -fXd lib/ lib-cjs/ intermediate/ src/ tmp/",
     "generate:base-svg": "node scripts/copy-base-svg.js --source=../svg-icons/icons --dest=./intermediate",
-    "convert:svg": "node scripts/convert.js --source=./intermediate --dest=./src --perIconDest=./src/atoms/svg --spriteDest=./src/atoms/svg-sprite --headlessPerIconDest=./src/atoms/headless-svg --headlessSpriteDest=./src/atoms/headless-svg-sprite --rtl=./intermediate/rtl.json --metadata=./tmp/metadata-svg.json",
-    "convert:fonts": "node scripts/convert-font.js --source=./src/utils/fonts --dest=./src/fonts --perIconDest=./src/atoms/fonts --headlessPerIconDest=./src/atoms/headless-fonts --codepointDest=./src/utils/fonts --rtl=./intermediate/rtl.json --metadata=./tmp/metadata-font.json",
+    "convert:svg": "node scripts/convert.js --source=./intermediate --dest=./src --perIconDest=./src/atoms/svg --spriteDest=./src/atoms/svg-sprite --headless --headlessPerIconDest=./src/atoms/headless-svg --rtl=./intermediate/rtl.json --metadata=./tmp/metadata-svg.json",
+    "convert:fonts": "node scripts/convert-font.js --source=./src/utils/fonts --dest=./src/fonts --perIconDest=./src/atoms/fonts --headless --headlessPerIconDest=./src/atoms/headless-fonts --codepointDest=./src/utils/fonts --rtl=./intermediate/rtl.json --metadata=./tmp/metadata-font.json",
     "convert:merge-metadata": "node scripts/merge-metadata.js --svgMetadata=./tmp/metadata-svg.json --fontMetadata=./tmp/metadata-font.json --output=./metadata.json",
     "generate:font-regular": "node ../../importer/generateFont.js --source=intermediate --dest=src/utils/fonts --iconType=Regular --codepoints=../../fonts/FluentSystemIcons-Regular.json",
     "generate:font-filled": "node ../../importer/generateFont.js --source=intermediate --dest=src/utils/fonts --iconType=Filled --codepoints=../../fonts/FluentSystemIcons-Filled.json",
@@ -61,6 +64,7 @@
   "files": [
     "docs/preview-features/*.md",
     "docs/build-transforms.md",
+    "docs/headless.md",
     "lib/",
     "lib-cjs/"
   ],
@@ -126,6 +130,33 @@
       "types": "./lib/providers.d.ts",
       "import": "./lib/providers.js",
       "require": "./lib-cjs/providers.js"
+    },
+    "./headless": {
+      "types": "./lib/headless/index.d.ts",
+      "import": "./lib/headless/index.js",
+      "require": "./lib-cjs/headless/index.js"
+    },
+    "./headless/fonts": {
+      "types": "./lib/headless/fonts/index.d.ts",
+      "import": "./lib/headless/fonts/index.js",
+      "require": "./lib-cjs/headless/fonts/index.js"
+    },
+    "./headless/styles.css": "./lib/headless/styles.css",
+    "./headless/fonts/styles.css": "./lib/headless/fonts/styles.css",
+    "./headless/svg/*": {
+      "types": "./lib/atoms/headless-svg/*.d.ts",
+      "import": "./lib/atoms/headless-svg/*.js",
+      "require": "./lib-cjs/atoms/headless-svg/*.js"
+    },
+    "./headless/fonts/*": {
+      "types": "./lib/atoms/headless-fonts/*.d.ts",
+      "import": "./lib/atoms/headless-fonts/*.js",
+      "require": "./lib-cjs/atoms/headless-fonts/*.js"
+    },
+    "./headless/utils": {
+      "types": "./lib/headless/utils.d.ts",
+      "import": "./lib/headless/utils.js",
+      "require": "./lib-cjs/headless/utils.js"
     }
   }
 }
diff --git a/packages/react-icons/scripts/build.js b/packages/react-icons/scripts/build.js
@@ -208,31 +208,40 @@ function addHeadlessExportMap(baseDir) {
       import: './lib/headless/fonts/index.js',
       require: './lib-cjs/headless/fonts/index.js',
     },
-    './headless/headless.css': './lib/headless/headless.css',
-    './headless/headless-fonts.css': './lib/headless/fonts/headless-fonts.css',
+    './headless/utils': {
+      types: './lib/headless/utils.d.ts',
+      import: './lib/headless/utils.js',
+      require: './lib-cjs/headless/utils.js',
+    },
+    './headless/styles.css': './lib/headless/styles.css',
+    './headless/fonts/styles.css': './lib/headless/fonts/styles.css',
     './headless/svg/*': {
       types: './lib/atoms/headless-svg/*.d.ts',
       import: './lib/atoms/headless-svg/*.js',
       require: './lib-cjs/atoms/headless-svg/*.js',
     },
-    './headless/svg-sprite/*': {
-      types: './lib/atoms/headless-svg-sprite/*.d.ts',
-      import: './lib/atoms/headless-svg-sprite/*.js',
-      require: './lib-cjs/atoms/headless-svg-sprite/*.js',
-    },
     './headless/fonts/*': {
       types: './lib/atoms/headless-fonts/*.d.ts',
       import: './lib/atoms/headless-fonts/*.js',
       require: './lib-cjs/atoms/headless-fonts/*.js',
     },
   };
 
+  // Only expose the headless svg-sprite subpath when those atoms were generated
+  if (existsSync(join(baseDir, 'src/atoms/headless-svg-sprite'))) {
+    headlessExports['./headless/svg-sprite/*'] = {
+      types: './lib/atoms/headless-svg-sprite/*.d.ts',
+      import: './lib/atoms/headless-svg-sprite/*.js',
+      require: './lib-cjs/atoms/headless-svg-sprite/*.js',
+    };
+  }
+
   // Add headless export maps
   Object.assign(pkg.exports, headlessExports);
   console.log(`  ✓ [exports] Set ${Object.keys(headlessExports).join(', ')}`);
 
   // Add headless CSS sideEffects entries
-  const headlessSideEffects = ['**/headless/fonts/headless-fonts.css', '**/headless/headless.css'];
+  const headlessSideEffects = ['**/headless/fonts/styles.css', '**/headless/styles.css'];
   pkg.sideEffects = [...headlessSideEffects];
   console.log(`  ✓ [sideEffects] Added ${headlessSideEffects.join(', ')}`);
 
diff --git a/packages/react-icons/scripts/convert.js b/packages/react-icons/scripts/convert.js
@@ -60,8 +60,8 @@ async function main() {
     },
   );
 
-  // 3. Generate headless per-icon output + SVG sprites (using headless import paths) - when --headless is enabled
-  if (HEADLESS_PER_ICON_DEST && HEADLESS_SPRITE_DEST) {
+  // 3. Generate headless per-icon output (+ SVG sprites when --headlessSpriteDest is provided) - when --headless is enabled
+  if (HEADLESS_PER_ICON_DEST) {
     await processPerIcon(srcFiles, HEADLESS_PER_ICON_DEST, HEADLESS_SPRITE_DEST, rtlMetadata, {
       svgImportPath: '../../headless/createFluentIcon',
       spriteTypeImportPath: '../../headless/createFluentIcon.svg-sprite',
diff --git a/packages/react-icons/src/headless/bundleIcon.tsx b/packages/react-icons/src/headless/bundleIcon.tsx
@@ -7,7 +7,7 @@ import type { FluentIcon } from './shared';
  * Headless bundleIcon — combines Filled and Regular icon variants.
  *
  * Renders both icons; the inactive variant gets `data-fui-icon-hidden`.
- * The shipped headless.css handles visibility via `[data-fui-icon-hidden] { display: none }`.
+ * The shipped styles.css handles visibility via `[data-fui-icon-hidden] { display: none }`.
  */
 export const bundleIcon = (FilledIcon: FluentIcon, RegularIcon: FluentIcon): FluentIcon => {
   const Component: FluentIcon = (props) => {
diff --git a/packages/react-icons/src/headless/fonts/styles.css b/packages/react-icons/src/headless/fonts/styles.css
@@ -4,7 +4,7 @@
  * files into the dependency graph. This enables font subsetting plugins to process them.
  *
  * Usage:
- *   import '@fluentui/react-icons/headless/headless-fonts.css';
+ *   import '@fluentui/react-icons/headless/fonts/styles.css';
  */
 
 @font-face {
diff --git a/packages/react-icons/src/headless/index.ts b/packages/react-icons/src/headless/index.ts
@@ -1,5 +1,5 @@
 // Headless Fluent Icons API
-// Import the shipped CSS file (headless.css) for default styling via data-attribute selectors.
+// Import the shipped CSS file (styles.css) for default styling via data-attribute selectors.
 
 // Types & constants
 export type { FluentIconsProps, FluentIcon, CreateFluentIconOptions } from './shared';
diff --git a/packages/react-icons/src/headless/shared.ts b/packages/react-icons/src/headless/shared.ts
@@ -1,5 +1,5 @@
 // Data attribute names used by headless icons for CSS targeting.
-// The shipped headless.css file uses these attribute selectors for styling.
+// The shipped styles.css file uses these attribute selectors for styling.
 
 /** Base data attribute applied to all icons (SVG and font). */
 export const DATA_FUI_ICON = 'data-fui-icon';
diff --git a/packages/react-icons/src/headless/styles.css b/packages/react-icons/src/headless/styles.css
diff --git a/packages/react-icons/src/headless/utils.ts b/packages/react-icons/src/headless/utils.ts
