From 8daa8d08dfb23ae703557526814c9c72d7449aa3 Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Tue, 13 Jun 2023 21:34:12 -0400
Subject: [PATCH 1/9] [v5] [colors] fix lint

---
 packages/colors/src/index.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/colors/src/index.ts b/packages/colors/src/index.ts
index 36d73ce691..0b96672411 100644
--- a/packages/colors/src/index.ts
+++ b/packages/colors/src/index.ts
@@ -15,4 +15,5 @@
  */
 
 export { Colors } from "./colors";
+// eslint-disable-next-line deprecation/deprecation
 export { LegacyColors } from "./legacyColors";

From bd9b91484a6311e7d90cca8793c22c9231476ef2 Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Wed, 14 Jun 2023 10:46:39 -0400
Subject: [PATCH 2/9] [v5] [icons] Defer loading of webpack loaders

---
 packages/icons/src/iconLoader.ts              | 37 ++++----
 .../webpackEagerPathsLoader.ts                | 41 +++++++++
 .../webpackLazyOncePathsLoader.ts             | 41 +++++++++
 .../webpack-loaders/webpackLazyPathsLoader.ts | 41 +++++++++
 packages/icons/src/webpackIconLoaders.ts      | 87 -------------------
 5 files changed, 142 insertions(+), 105 deletions(-)
 create mode 100644 packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
 create mode 100644 packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts
 create mode 100644 packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts
 delete mode 100644 packages/icons/src/webpackIconLoaders.ts

diff --git a/packages/icons/src/iconLoader.ts b/packages/icons/src/iconLoader.ts
index 701c949b9b..2a7a327126 100644
--- a/packages/icons/src/iconLoader.ts
+++ b/packages/icons/src/iconLoader.ts
@@ -17,7 +17,6 @@
 import { type IconName, IconNames } from "./iconNames";
 import { type IconPaths, IconSize } from "./iconTypes";
 import { wrapWithTimer } from "./loaderUtils";
-import { webpackEagerPathsLoader, webpackLazyOncePathsLoader, webpackLazyPathsLoader } from "./webpackIconLoaders";
 
 /** Given an icon name and size, loads the icon paths that define it. */
 export type IconPathsLoader = (iconName: IconName, iconSize: IconSize) => Promise<IconPaths>;
@@ -32,6 +31,24 @@ export interface IconLoaderOptions {
     loader?: "webpack-lazy-once" | "webpack-lazy" | "webpack-eager" | IconPathsLoader;
 }
 
+async function getLoaderFn(options: IconLoaderOptions): Promise<IconPathsLoader> {
+    const { loader = singleton.defaultLoader } = options;
+
+    if (typeof loader === "function") {
+        return loader;
+    } else if (loader === "webpack-eager") {
+        return (await import("./webpack-loaders/webpackEagerPathsLoader")).webpackEagerPathsLoader;
+    } else if (loader === "webpack-lazy") {
+        return (await import("./webpack-loaders/webpackLazyPathsLoader")).webpackLazyPathsLoader;
+    } else if (loader === "webpack-lazy-once") {
+        return (await import("./webpack-loaders/webpackLazyOncePathsLoader")).webpackLazyOncePathsLoader;
+    } else {
+        // no bundler-aware dynamic loader available, so we fall back to a static one
+        const { getIconPaths } = await import("./iconPaths");
+        return async (name, size) => getIconPaths(name, size);
+    }
+}
+
 /**
  * Blueprint icons loader.
  */
@@ -112,23 +129,7 @@ export class Icons {
             return;
         }
 
-        const { loader = singleton.defaultLoader } = options;
-
-        const loaderFn =
-            typeof loader == "function"
-                ? loader
-                : loader === "webpack-eager"
-                ? webpackEagerPathsLoader
-                : loader === "webpack-lazy"
-                ? webpackLazyPathsLoader
-                : loader === "webpack-lazy-once"
-                ? webpackLazyOncePathsLoader
-                : undefined;
-
-        if (loaderFn === undefined) {
-            console.error(`[Blueprint] Unknown icon loader: ${loader}`);
-            return;
-        }
+        const loaderFn = await getLoaderFn(options);
 
         try {
             const supportedSize = size < IconSize.LARGE ? IconSize.STANDARD : IconSize.LARGE;
diff --git a/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts b/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
new file mode 100644
index 0000000000..6522e1d320
--- /dev/null
+++ b/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { IconPathsLoader } from "../iconLoader";
+import { IconSize } from "../iconTypes";
+
+/**
+ * An "eager" webpack module loader.
+ *
+ * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
+ */
+export const webpackEagerPathsLoader: IconPathsLoader = async (name, size) => {
+    return (
+        size === IconSize.STANDARD
+            ? await import(
+                  /* webpackChunkName: "blueprint-icons-16px" */
+                  /* webpackInclude: /\.js$/ */
+                  /* webpackMode: "eager" */
+                  `./generated/16px/paths/${name}`
+              )
+            : await import(
+                  /* webpackChunkName: "blueprint-icons-20px" */
+                  /* webpackInclude: /\.js$/ */
+                  /* webpackMode: "eager" */
+                  `./generated/20px/paths/${name}`
+              )
+    ).default;
+};
diff --git a/packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts b/packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts
new file mode 100644
index 0000000000..5e2e333ce2
--- /dev/null
+++ b/packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { IconPathsLoader } from "../iconLoader";
+import { IconSize } from "../iconTypes";
+
+/**
+ * The default icon paths loader, using webpack's "lazy-once" mode.
+ *
+ * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
+ */
+export const webpackLazyOncePathsLoader: IconPathsLoader = async (name, size) => {
+    return (
+        size === IconSize.STANDARD
+            ? await import(
+                  /* webpackChunkName: "blueprint-icons-16px" */
+                  /* webpackInclude: /\.js$/ */
+                  /* webpackMode: "lazy-once" */
+                  `./generated/16px/paths/${name}`
+              )
+            : await import(
+                  /* webpackChunkName: "blueprint-icons-20px" */
+                  /* webpackInclude: /\.js$/ */
+                  /* webpackMode: "lazy-once" */
+                  `./generated/20px/paths/${name}`
+              )
+    ).default;
+};
diff --git a/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts b/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts
new file mode 100644
index 0000000000..6c877dba32
--- /dev/null
+++ b/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { IconPathsLoader } from "../iconLoader";
+import { IconSize } from "../iconTypes";
+
+/**
+ * A "lazy" webpack module loader.
+ *
+ * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
+ */
+export const webpackLazyPathsLoader: IconPathsLoader = async (name, size) => {
+    return (
+        size === IconSize.STANDARD
+            ? await import(
+                  /* webpackChunkName: "blueprint-icons-16px" */
+                  /* webpackInclude: /\.js$/ */
+                  /* webpackMode: "lazy" */
+                  `./generated/16px/paths/${name}`
+              )
+            : await import(
+                  /* webpackChunkName: "blueprint-icons-20px" */
+                  /* webpackInclude: /\.js$/ */
+                  /* webpackMode: "lazy" */
+                  `./generated/20px/paths/${name}`
+              )
+    ).default;
+};
diff --git a/packages/icons/src/webpackIconLoaders.ts b/packages/icons/src/webpackIconLoaders.ts
deleted file mode 100644
index 5eec8247cd..0000000000
--- a/packages/icons/src/webpackIconLoaders.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-/*
- * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import type { IconPathsLoader } from "./iconLoader";
-import { IconSize } from "./iconTypes";
-
-/**
- * The default icon paths loader, using webpack's "lazy-once" mode.
- *
- * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
- */
-export const webpackLazyOncePathsLoader: IconPathsLoader = async (name, size) => {
-    return (
-        size === IconSize.STANDARD
-            ? await import(
-                  /* webpackChunkName: "blueprint-icons-16px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "lazy-once" */
-                  `./generated/16px/paths/${name}`
-              )
-            : await import(
-                  /* webpackChunkName: "blueprint-icons-20px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "lazy-once" */
-                  `./generated/20px/paths/${name}`
-              )
-    ).default;
-};
-
-/**
- * A "lazy" webpack module loader.
- *
- * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
- */
-export const webpackLazyPathsLoader: IconPathsLoader = async (name, size) => {
-    return (
-        size === IconSize.STANDARD
-            ? await import(
-                  /* webpackChunkName: "blueprint-icons-16px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "lazy" */
-                  `./generated/16px/paths/${name}`
-              )
-            : await import(
-                  /* webpackChunkName: "blueprint-icons-20px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "lazy" */
-                  `./generated/20px/paths/${name}`
-              )
-    ).default;
-};
-
-/**
- * An "eager" webpack module loader.
- *
- * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
- */
-export const webpackEagerPathsLoader: IconPathsLoader = async (name, size) => {
-    return (
-        size === IconSize.STANDARD
-            ? await import(
-                  /* webpackChunkName: "blueprint-icons-16px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "eager" */
-                  `./generated/16px/paths/${name}`
-              )
-            : await import(
-                  /* webpackChunkName: "blueprint-icons-20px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "eager" */
-                  `./generated/20px/paths/${name}`
-              )
-    ).default;
-};

From 91ae5e0d631a1b4b9f70bbe2a3880ff15033c112 Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Wed, 14 Jun 2023 11:23:59 -0400
Subject: [PATCH 3/9] fix paths in webpack-loaders

---
 packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts | 4 ++--
 .../icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts   | 4 ++--
 packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts  | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts b/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
index 6522e1d320..260c9e8126 100644
--- a/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
+++ b/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
@@ -29,13 +29,13 @@ export const webpackEagerPathsLoader: IconPathsLoader = async (name, size) => {
                   /* webpackChunkName: "blueprint-icons-16px" */
                   /* webpackInclude: /\.js$/ */
                   /* webpackMode: "eager" */
-                  `./generated/16px/paths/${name}`
+                  `../generated/16px/paths/${name}`
               )
             : await import(
                   /* webpackChunkName: "blueprint-icons-20px" */
                   /* webpackInclude: /\.js$/ */
                   /* webpackMode: "eager" */
-                  `./generated/20px/paths/${name}`
+                  `../generated/20px/paths/${name}`
               )
     ).default;
 };
diff --git a/packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts b/packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts
index 5e2e333ce2..3a3ffc08f1 100644
--- a/packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts
+++ b/packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts
@@ -29,13 +29,13 @@ export const webpackLazyOncePathsLoader: IconPathsLoader = async (name, size) =>
                   /* webpackChunkName: "blueprint-icons-16px" */
                   /* webpackInclude: /\.js$/ */
                   /* webpackMode: "lazy-once" */
-                  `./generated/16px/paths/${name}`
+                  `../generated/16px/paths/${name}`
               )
             : await import(
                   /* webpackChunkName: "blueprint-icons-20px" */
                   /* webpackInclude: /\.js$/ */
                   /* webpackMode: "lazy-once" */
-                  `./generated/20px/paths/${name}`
+                  `../generated/20px/paths/${name}`
               )
     ).default;
 };
diff --git a/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts b/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts
index 6c877dba32..1052d6f329 100644
--- a/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts
+++ b/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts
@@ -29,13 +29,13 @@ export const webpackLazyPathsLoader: IconPathsLoader = async (name, size) => {
                   /* webpackChunkName: "blueprint-icons-16px" */
                   /* webpackInclude: /\.js$/ */
                   /* webpackMode: "lazy" */
-                  `./generated/16px/paths/${name}`
+                  `../generated/16px/paths/${name}`
               )
             : await import(
                   /* webpackChunkName: "blueprint-icons-20px" */
                   /* webpackInclude: /\.js$/ */
                   /* webpackMode: "lazy" */
-                  `./generated/20px/paths/${name}`
+                  `../generated/20px/paths/${name}`
               )
     ).default;
 };

From 39a71df286b47a740d06544500bb258fc8969a81 Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Wed, 14 Jun 2023 11:24:16 -0400
Subject: [PATCH 4/9] fix #6220, add example to verify fix

---
 packages/core/src/components/icon/icon.md     | 22 ++++++-
 .../iconGeneratedComponentExample.tsx         | 63 +++++++++++++++++++
 .../src/examples/core-examples/index.ts       |  3 +-
 .../scripts/generate-icon-components.mjs      |  3 +
 packages/icons/scripts/iconComponent.tsx.hbs  | 10 ++-
 5 files changed, 92 insertions(+), 9 deletions(-)
 create mode 100644 packages/docs-app/src/examples/core-examples/iconGeneratedComponentExample.tsx

diff --git a/packages/core/src/components/icon/icon.md b/packages/core/src/components/icon/icon.md
index 6bc496df20..6d73e8054d 100644
--- a/packages/core/src/components/icon/icon.md
+++ b/packages/core/src/components/icon/icon.md
@@ -23,7 +23,13 @@ the name as a string, these components render `<Icon icon="..." />` under the ho
 Use the `<Icon>` component to easily render __SVG icons__ in React. The `icon`
 prop is typed such that editors can offer autocomplete for known icon names. The
 optional `size` prop determines the exact width and height of the icon
-image; the icon element itself can be sized separately using CSS.
+image; the icon element itself can be also be sized using CSS.
+
+<div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
+
+Icons may be configured to load in various ways, see ["Loading icons"](#icons/loading-icons).
+
+</div>
 
 The HTML element rendered by `<Icon>` can be customized with the `tagName` prop
 (defaults to `span`), and additional props are passed to this element.
@@ -68,7 +74,19 @@ Custom sizes are supported. The following React component:
 
 @interface IconProps
 
-@## CSS
+@## Static components
+
+The `<Icon>` component loads icon paths via dynamic module imports by default. An alternative API
+is available in the __@blueprintjs/icons__ package which provides static imports of each icon as
+a React component. The example below uses the `<Calendar>` component.
+
+Note that some `<Icon>` props are not yet supported for these components, such as `intent`.
+
+@reactExample IconGeneratedComponentExample
+
+@interface SVGIconProps
+
+@## CSS API
 
 The CSS-only icons API uses the __icon fonts__ from the __@blueprintjs/icons__ package.
 Note that _none of Blueprint's React components use the icon font_; it is only provided
diff --git a/packages/docs-app/src/examples/core-examples/iconGeneratedComponentExample.tsx b/packages/docs-app/src/examples/core-examples/iconGeneratedComponentExample.tsx
new file mode 100644
index 0000000000..0f3bba289a
--- /dev/null
+++ b/packages/docs-app/src/examples/core-examples/iconGeneratedComponentExample.tsx
@@ -0,0 +1,63 @@
+/*
+ * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as React from "react";
+
+import { H5, Label, Slider } from "@blueprintjs/core";
+import { Example, ExampleProps } from "@blueprintjs/docs-theme";
+import { Calendar, IconSize } from "@blueprintjs/icons";
+
+interface ExampleState {
+    iconSize: number;
+}
+
+export class IconGeneratedComponentExample extends React.PureComponent<ExampleProps, ExampleState> {
+    public state: ExampleState = {
+        iconSize: IconSize.STANDARD,
+    };
+
+    private handleIconSizeChange = (iconSize: number) => this.setState({ iconSize });
+
+    private iconSizeLabelId = "icon-size-label";
+
+    public render() {
+        const { iconSize } = this.state;
+
+        const options = (
+            <>
+                <H5>Props</H5>
+                <Label id={this.iconSizeLabelId}>Icon size</Label>
+                <Slider
+                    labelStepSize={MAX_ICON_SIZE / 5}
+                    min={0}
+                    max={MAX_ICON_SIZE}
+                    showTrackFill={false}
+                    value={iconSize}
+                    onChange={this.handleIconSizeChange}
+                    handleHtmlProps={{ "aria-labelledby": this.iconSizeLabelId }}
+                />
+            </>
+        );
+
+        return (
+            <Example options={options} {...this.props}>
+                <Calendar size={iconSize} />
+            </Example>
+        );
+    }
+}
+
+const MAX_ICON_SIZE = 100;
diff --git a/packages/docs-app/src/examples/core-examples/index.ts b/packages/docs-app/src/examples/core-examples/index.ts
index 020c6ba73a..9b82562c05 100644
--- a/packages/docs-app/src/examples/core-examples/index.ts
+++ b/packages/docs-app/src/examples/core-examples/index.ts
@@ -40,7 +40,8 @@ export { HotkeyPiano } from "./hotkeyPiano";
 export { HotkeyTesterExample } from "./hotkeyTesterExample";
 export { HotkeysTarget2Example } from "./hotkeysTarget2Example";
 export { HTMLSelectExample } from "./htmlSelectExample";
-export * from "./iconExample";
+export { IconExample } from "./iconExample";
+export { IconGeneratedComponentExample } from "./iconGeneratedComponentExample";
 export * from "./menuExample";
 export { MenuItemExample } from "./menuItemExample";
 export * from "./multiSliderExample";
diff --git a/packages/icons/scripts/generate-icon-components.mjs b/packages/icons/scripts/generate-icon-components.mjs
index e9b3710a56..47566141c0 100644
--- a/packages/icons/scripts/generate-icon-components.mjs
+++ b/packages/icons/scripts/generate-icon-components.mjs
@@ -66,6 +66,9 @@ for (const [iconName, icon16pxPath] of Object.entries(iconPaths[16])) {
     }
     writeFileSync(
         join(generatedSrcDir, `components/${iconName}.tsx`),
+        // Notes on icon component template implementation:
+        //  - path "translation" transform must use "viewbox" dimensions, not "size", in order to avoid issues
+        //    like https://github.com/palantir/blueprint/issues/6220
         iconComponentTemplate({
             iconName,
             icon16pxPath,
diff --git a/packages/icons/scripts/iconComponent.tsx.hbs b/packages/icons/scripts/iconComponent.tsx.hbs
index a431f9c228..8ce8758639 100644
--- a/packages/icons/scripts/iconComponent.tsx.hbs
+++ b/packages/icons/scripts/iconComponent.tsx.hbs
@@ -19,15 +19,13 @@ import { IconSize } from "../../iconTypes";
 import { SVGIconContainer } from "../../svgIconContainer";
 
 export const {{pascalCase iconName}}: React.FC<SVGIconProps> = React.forwardRef<any, SVGIconProps>((props, ref) => {
-    const translation = `${-1 * props.size! / {{pathScaleFactor}} / 2}`;
+    const isLarge = props.size! >= IconSize.LARGE;
+    const pixelGridSize = isLarge ? IconSize.LARGE : IconSize.STANDARD;
+    const translation = `${-1 * pixelGridSize / {{pathScaleFactor}} / 2}`;
     return (
         <SVGIconContainer iconName="{{iconName}}" ref={ref}  {...props}>
             <path
-                d={
-                    props.size! < IconSize.LARGE
-                        ? "{{icon16pxPath}}"
-                        : "{{icon20pxPath}}"
-                }
+                d={isLarge ? "{{icon20pxPath}}" : "{{icon16pxPath}}"}
                 fillRule="evenodd"
                 transform-origin="center"
                 transform={`scale({{pathScaleFactor}}, -{{pathScaleFactor}}) translate(${translation}, ${translation})`}

From 0b262638bda6bdb1e324f7839dfb8e0ffd4695ac Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Wed, 14 Jun 2023 11:55:13 -0400
Subject: [PATCH 5/9] Remove extra loaders

---
 packages/icons/src/iconLoader.ts              | 16 +++-----
 packages/icons/src/loading-icons.md           | 35 ++++++++++++----
 .../src/paths-loaders/simplePathsLoader.ts    | 28 +++++++++++++
 .../webpackLazyOncePathsLoader.ts             |  0
 .../webpackEagerPathsLoader.ts                | 41 -------------------
 .../webpack-loaders/webpackLazyPathsLoader.ts | 41 -------------------
 6 files changed, 60 insertions(+), 101 deletions(-)
 create mode 100644 packages/icons/src/paths-loaders/simplePathsLoader.ts
 rename packages/icons/src/{webpack-loaders => paths-loaders}/webpackLazyOncePathsLoader.ts (100%)
 delete mode 100644 packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
 delete mode 100644 packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts

diff --git a/packages/icons/src/iconLoader.ts b/packages/icons/src/iconLoader.ts
index 2a7a327126..a3846d1202 100644
--- a/packages/icons/src/iconLoader.ts
+++ b/packages/icons/src/iconLoader.ts
@@ -26,9 +26,9 @@ export interface IconLoaderOptions {
      * The id of a built-in loader, or a custom loader function.
      *
      * @see https://blueprintjs.com/docs/versions/5/#icons/loading-icons
-     * @default "webpack-lazy-once"
+     * @default undefined
      */
-    loader?: "webpack-lazy-once" | "webpack-lazy" | "webpack-eager" | IconPathsLoader;
+    loader?: "static" | "webpack-lazy-once" | IconPathsLoader;
 }
 
 async function getLoaderFn(options: IconLoaderOptions): Promise<IconPathsLoader> {
@@ -36,16 +36,10 @@ async function getLoaderFn(options: IconLoaderOptions): Promise<IconPathsLoader>
 
     if (typeof loader === "function") {
         return loader;
-    } else if (loader === "webpack-eager") {
-        return (await import("./webpack-loaders/webpackEagerPathsLoader")).webpackEagerPathsLoader;
-    } else if (loader === "webpack-lazy") {
-        return (await import("./webpack-loaders/webpackLazyPathsLoader")).webpackLazyPathsLoader;
     } else if (loader === "webpack-lazy-once") {
-        return (await import("./webpack-loaders/webpackLazyOncePathsLoader")).webpackLazyOncePathsLoader;
+        return (await import("./paths-loaders/webpackLazyOncePathsLoader")).webpackLazyOncePathsLoader;
     } else {
-        // no bundler-aware dynamic loader available, so we fall back to a static one
-        const { getIconPaths } = await import("./iconPaths");
-        return async (name, size) => getIconPaths(name, size);
+        return (await import("./paths-loaders/simplePathsLoader")).simplePathsLoader;
     }
 }
 
@@ -54,7 +48,7 @@ async function getLoaderFn(options: IconLoaderOptions): Promise<IconPathsLoader>
  */
 export class Icons {
     /** @internal */
-    public defaultLoader: Required<IconLoaderOptions>["loader"] = "webpack-lazy-once";
+    public defaultLoader: IconLoaderOptions["loader"] = "webpack-lazy-once";
 
     /** @internal */
     public loadedIconPaths16: Map<IconName, IconPaths> = new Map();
diff --git a/packages/icons/src/loading-icons.md b/packages/icons/src/loading-icons.md
index b8f8c5a802..17561bd4a7 100644
--- a/packages/icons/src/loading-icons.md
+++ b/packages/icons/src/loading-icons.md
@@ -75,11 +75,12 @@ to its available APIs.
     ```ts
     import { Icons } from "@blueprintjs/icons";
 
-    // using the default annotated Webpack loader, which uses the "lazy-once" mode
+    // using the default dynamic loader, which uses Webpack's "lazy-once" mode
     await Icons.loadAll();
 
-    // using an "eager" Webpack loader, which bundles icon modules in a way that mimics Blueprint v4.x behavior
-    await Icons.loadAll({ loader: "webpack-eager" });
+    // using a "simple" loader, which uses a dynamic import without any path arguments and thus does not require
+    // knowlege of any JS bundler specifics
+    await Icons.loadAll({ loader: "simple" });
     ```
 
 2. Use static imports to load all icon paths statically (simpler, does not require knowledge of bundler specifics).
@@ -97,9 +98,27 @@ to its available APIs.
     Any usage of `<Icon icon="..." />` will trigger a network request to fetch the individual icon contents chunk.
 
     ```ts
-    import { Icons } from "@blueprintjs/icons";
-
-    Icons.setLoaderOptions({ loader: "webpack-lazy" });
+    import { Icons, IconSize, IconPathsLoader } from "@blueprintjs/icons";
+
+    const lazyLoader: IconPathsLoader = async (name, size) => {
+        return (
+            size === IconSize.STANDARD
+                ? await import(
+                    /* webpackChunkName: "blueprint-icons-16px" */
+                    /* webpackInclude: /\.js$/ */
+                    /* webpackMode: "lazy" */
+                    `@blueprintjs/icons/lib/esm/generated/16px/paths/${name}`
+                )
+                : await import(
+                    /* webpackChunkName: "blueprint-icons-20px" */
+                    /* webpackInclude: /\.js$/ */
+                    /* webpackMode: "lazy" */
+                    `@blueprintjs/icons/lib/esm/generated/20px/paths/${name}`
+                )
+        ).default;
+    };
+
+    Icons.setLoaderOptions({ loader: lazyLoader });
     ```
 
 4. Load some icon paths up front (dynamically) with network requests, and the rest lazily/on-demand.
@@ -107,11 +126,11 @@ to its available APIs.
     ```ts
     import { Icons } from "@blueprintjs/icons";
 
-    Icons.setLoaderOptions({ loader: "webpack-lazy" });
+    Icons.setLoaderOptions({ loader: lazyLoader });
     await Icons.load(["download", "caret-down", "endorsed", "help", "lock"]);
     ```
 
-5. Use a custom loader for more control.
+5. Custom loaders allow usage with other bundlers, like Vite for example.
 
     ```ts
     // specify a custom loader function for an alternative bundler, for example Vite
diff --git a/packages/icons/src/paths-loaders/simplePathsLoader.ts b/packages/icons/src/paths-loaders/simplePathsLoader.ts
new file mode 100644
index 0000000000..8ee76d71f4
--- /dev/null
+++ b/packages/icons/src/paths-loaders/simplePathsLoader.ts
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { IconPathsLoader } from "../iconLoader";
+
+/**
+ * A simple module loader for icon paths that does not require any knowledge of JS bundlers.
+ */
+export const simplePathsLoader: IconPathsLoader = async (name, size) => {
+    const { getIconPaths } = await import(
+        /* webpackChunkName: "blueprint-icons-all-paths" */
+        "../iconPaths"
+    );
+    return getIconPaths(name, size);
+};
diff --git a/packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts b/packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts
similarity index 100%
rename from packages/icons/src/webpack-loaders/webpackLazyOncePathsLoader.ts
rename to packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts
diff --git a/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts b/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
deleted file mode 100644
index 260c9e8126..0000000000
--- a/packages/icons/src/webpack-loaders/webpackEagerPathsLoader.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-/*
- * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import type { IconPathsLoader } from "../iconLoader";
-import { IconSize } from "../iconTypes";
-
-/**
- * An "eager" webpack module loader.
- *
- * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
- */
-export const webpackEagerPathsLoader: IconPathsLoader = async (name, size) => {
-    return (
-        size === IconSize.STANDARD
-            ? await import(
-                  /* webpackChunkName: "blueprint-icons-16px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "eager" */
-                  `../generated/16px/paths/${name}`
-              )
-            : await import(
-                  /* webpackChunkName: "blueprint-icons-20px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "eager" */
-                  `../generated/20px/paths/${name}`
-              )
-    ).default;
-};
diff --git a/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts b/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts
deleted file mode 100644
index 1052d6f329..0000000000
--- a/packages/icons/src/webpack-loaders/webpackLazyPathsLoader.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-/*
- * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import type { IconPathsLoader } from "../iconLoader";
-import { IconSize } from "../iconTypes";
-
-/**
- * A "lazy" webpack module loader.
- *
- * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
- */
-export const webpackLazyPathsLoader: IconPathsLoader = async (name, size) => {
-    return (
-        size === IconSize.STANDARD
-            ? await import(
-                  /* webpackChunkName: "blueprint-icons-16px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "lazy" */
-                  `../generated/16px/paths/${name}`
-              )
-            : await import(
-                  /* webpackChunkName: "blueprint-icons-20px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "lazy" */
-                  `../generated/20px/paths/${name}`
-              )
-    ).default;
-};

From c98a395a38c9ba0609685e09a9e3f51e4b914356 Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Wed, 14 Jun 2023 12:13:30 -0400
Subject: [PATCH 6/9] Fix typo

---
 packages/docs-app/src/components/icons.tsx | 2 +-
 packages/icons/src/iconLoader.ts           | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/docs-app/src/components/icons.tsx b/packages/docs-app/src/components/icons.tsx
index d8b86f6b16..f85d6df7e1 100644
--- a/packages/docs-app/src/components/icons.tsx
+++ b/packages/docs-app/src/components/icons.tsx
@@ -23,7 +23,7 @@ import { Icons as IconLoader } from "@blueprintjs/icons";
 import { DocsIcon, DocsIconProps as Icon } from "./docsIcon";
 
 // this compiles all the icon modules into this chunk, so async Icon.load() calls don't block later
-IconLoader.loadAll({ loader: "webpack-eager" });
+IconLoader.loadAll({ loader: "simple" });
 
 const ICONS_PER_ROW = 5;
 
diff --git a/packages/icons/src/iconLoader.ts b/packages/icons/src/iconLoader.ts
index a3846d1202..0a98c517c0 100644
--- a/packages/icons/src/iconLoader.ts
+++ b/packages/icons/src/iconLoader.ts
@@ -26,9 +26,9 @@ export interface IconLoaderOptions {
      * The id of a built-in loader, or a custom loader function.
      *
      * @see https://blueprintjs.com/docs/versions/5/#icons/loading-icons
-     * @default undefined
+     * @default undefined (equivalent to "simple")
      */
-    loader?: "static" | "webpack-lazy-once" | IconPathsLoader;
+    loader?: "simple" | "webpack-lazy-once" | IconPathsLoader;
 }
 
 async function getLoaderFn(options: IconLoaderOptions): Promise<IconPathsLoader> {

From a5cf4487c88a79c2acd76bc428c052f65c8860fc Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Wed, 14 Jun 2023 13:20:56 -0400
Subject: [PATCH 7/9] Remove built-in webpack loaders

---
 .../core/src/components/button/buttons.tsx    |  6 +-
 packages/docs-app/src/components/icons.tsx    |  4 --
 packages/docs-app/src/index.tsx               |  4 ++
 .../icons/src/{iconPaths.ts => allPaths.ts}   |  0
 packages/icons/src/iconLoader.ts              | 12 ++--
 packages/icons/src/index.ts                   |  2 +-
 packages/icons/src/loading-icons.md           | 65 +++++++++++--------
 ...simplePathsLoader.ts => allPathsLoader.ts} |  6 +-
 .../paths-loaders/splitPathsBySizeLoader.ts   | 44 +++++++++++++
 .../webpackLazyOncePathsLoader.ts             | 48 +++++++-------
 10 files changed, 123 insertions(+), 68 deletions(-)
 rename packages/icons/src/{iconPaths.ts => allPaths.ts} (100%)
 rename packages/icons/src/paths-loaders/{simplePathsLoader.ts => allPathsLoader.ts} (81%)
 create mode 100644 packages/icons/src/paths-loaders/splitPathsBySizeLoader.ts

diff --git a/packages/core/src/components/button/buttons.tsx b/packages/core/src/components/button/buttons.tsx
index 061755abb3..e96a89dfef 100644
--- a/packages/core/src/components/button/buttons.tsx
+++ b/packages/core/src/components/button/buttons.tsx
@@ -17,13 +17,11 @@
 import classNames from "classnames";
 import * as React from "react";
 
-import { IconSize } from "@blueprintjs/icons";
-
 import { Classes, Utils } from "../../common";
 import { DISPLAYNAME_PREFIX, removeNonHTMLProps } from "../../common/props";
 import { mergeRefs } from "../../common/refs";
 import { Icon } from "../icon/icon";
-import { Spinner } from "../spinner/spinner";
+import { Spinner, SpinnerSize } from "../spinner/spinner";
 import { AnchorButtonProps, ButtonProps } from "./buttonProps";
 
 /**
@@ -158,7 +156,7 @@ function renderButtonContents<E extends HTMLAnchorElement | HTMLButtonElement>(
     const hasTextContent = !Utils.isReactNodeEmpty(text) || !Utils.isReactNodeEmpty(children);
     return (
         <>
-            {loading && <Spinner key="loading" className={Classes.BUTTON_SPINNER} size={IconSize.LARGE} />}
+            {loading && <Spinner key="loading" className={Classes.BUTTON_SPINNER} size={SpinnerSize.SMALL} />}
             <Icon key="leftIcon" icon={icon} />
             {hasTextContent && (
                 <span key="text" className={Classes.BUTTON_TEXT}>
diff --git a/packages/docs-app/src/components/icons.tsx b/packages/docs-app/src/components/icons.tsx
index f85d6df7e1..c633b0d1fe 100644
--- a/packages/docs-app/src/components/icons.tsx
+++ b/packages/docs-app/src/components/icons.tsx
@@ -18,13 +18,9 @@ import * as React from "react";
 
 import { Classes, H3, InputGroup, NonIdealState } from "@blueprintjs/core";
 import { smartSearch } from "@blueprintjs/docs-theme";
-import { Icons as IconLoader } from "@blueprintjs/icons";
 
 import { DocsIcon, DocsIconProps as Icon } from "./docsIcon";
 
-// this compiles all the icon modules into this chunk, so async Icon.load() calls don't block later
-IconLoader.loadAll({ loader: "simple" });
-
 const ICONS_PER_ROW = 5;
 
 export interface IconsState {
diff --git a/packages/docs-app/src/index.tsx b/packages/docs-app/src/index.tsx
index fc05f0a94f..8c8aea2467 100644
--- a/packages/docs-app/src/index.tsx
+++ b/packages/docs-app/src/index.tsx
@@ -18,11 +18,15 @@ import * as ReactDOM from "react-dom";
 
 import { docsData } from "@blueprintjs/docs-data";
 import { createDefaultRenderers, ReactDocsTagRenderer, ReactExampleTagRenderer } from "@blueprintjs/docs-theme";
+import { Icons } from "@blueprintjs/icons";
 
 import { BlueprintDocs } from "./components/blueprintDocs";
 import * as ReactDocs from "./tags/reactDocs";
 import { reactExamples } from "./tags/reactExamples";
 
+// load all icons up front so that they do not experience a flash of unstyled content (but we don't need to block on this promise)
+Icons.loadAll();
+
 const reactDocs = new ReactDocsTagRenderer(ReactDocs as any);
 const reactExample = new ReactExampleTagRenderer(reactExamples);
 
diff --git a/packages/icons/src/iconPaths.ts b/packages/icons/src/allPaths.ts
similarity index 100%
rename from packages/icons/src/iconPaths.ts
rename to packages/icons/src/allPaths.ts
diff --git a/packages/icons/src/iconLoader.ts b/packages/icons/src/iconLoader.ts
index 0a98c517c0..724ffd8da5 100644
--- a/packages/icons/src/iconLoader.ts
+++ b/packages/icons/src/iconLoader.ts
@@ -26,9 +26,9 @@ export interface IconLoaderOptions {
      * The id of a built-in loader, or a custom loader function.
      *
      * @see https://blueprintjs.com/docs/versions/5/#icons/loading-icons
-     * @default undefined (equivalent to "simple")
+     * @default undefined (equivalent to "split-by-size")
      */
-    loader?: "simple" | "webpack-lazy-once" | IconPathsLoader;
+    loader?: "split-by-size" | "all" | IconPathsLoader;
 }
 
 async function getLoaderFn(options: IconLoaderOptions): Promise<IconPathsLoader> {
@@ -36,10 +36,10 @@ async function getLoaderFn(options: IconLoaderOptions): Promise<IconPathsLoader>
 
     if (typeof loader === "function") {
         return loader;
-    } else if (loader === "webpack-lazy-once") {
-        return (await import("./paths-loaders/webpackLazyOncePathsLoader")).webpackLazyOncePathsLoader;
+    } else if (loader === "all") {
+        return (await import("./paths-loaders/allPathsLoader")).allPathsLoader;
     } else {
-        return (await import("./paths-loaders/simplePathsLoader")).simplePathsLoader;
+        return (await import("./paths-loaders/splitPathsBySizeLoader")).splitPathsBySizeLoader;
     }
 }
 
@@ -48,7 +48,7 @@ async function getLoaderFn(options: IconLoaderOptions): Promise<IconPathsLoader>
  */
 export class Icons {
     /** @internal */
-    public defaultLoader: IconLoaderOptions["loader"] = "webpack-lazy-once";
+    public defaultLoader: IconLoaderOptions["loader"] = "split-by-size";
 
     /** @internal */
     public loadedIconPaths16: Map<IconName, IconPaths> = new Map();
diff --git a/packages/icons/src/index.ts b/packages/icons/src/index.ts
index 5d2775b24b..7e28ea7f03 100644
--- a/packages/icons/src/index.ts
+++ b/packages/icons/src/index.ts
@@ -15,7 +15,7 @@
  */
 
 // N.B. these named imports will trigger bundlers to statically loads all icon path modules
-export { IconSvgPaths16, IconSvgPaths20, getIconPaths } from "./iconPaths";
+export { IconSvgPaths16, IconSvgPaths20, getIconPaths } from "./allPaths";
 
 export { Icons, IconLoaderOptions, IconPathsLoader } from "./iconLoader";
 export { SVGIconProps } from "./svgIconProps";
diff --git a/packages/icons/src/loading-icons.md b/packages/icons/src/loading-icons.md
index 17561bd4a7..b022b7944c 100644
--- a/packages/icons/src/loading-icons.md
+++ b/packages/icons/src/loading-icons.md
@@ -58,42 +58,56 @@ These usability benefits do come at the cost of some some extra work for Bluepri
 Blueprint user) in order for these icons to be available at runtime. With the string literal API, **Blueprint code is
 importing icon modules for you**.  Let's take a look at this required configuration.
 
-<div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
+1. Use the default dynamic import API to bundle icon paths into two chunks (standard & large sizes) separate from your
+    entry point. This requires a bundler or module loader which can handle `await import()` statements. These statements
+    are annotated with [Webpack magic comments](https://webpack.js.org/api/module-methods/#magic-comments), but they do
+    not explicitly require Webpack to function.
 
-The following strategies assume you are bundling with Webpack; if you are using a different bundler then you will have to adapt
-to its available APIs.
-</div>
-
-1. Use built-in dynamic import APIa to load all icon paths statically, similar to behavior in Blueprint versions prior to v5.x.
-
-    This results in the largest bundle size for your main chunk.
+    With this API, the first usage of any icon in a given size (standard or large) will trigger a request to fetch a
+    bundle containing all the icon paths of that size. This behavior is enabled by default since the standard icon size
+    is used more frequently in Blueprint than the large size, and thus we can get a small performance enhancement by
+    deferring the loading of large icons.
 
-    In the entry point for your bundle, use `Icons.loadAll()` with one of the built-in webpack-annotated loader functions.
-    This will to ensure that webpack will bundle all the icon modules in your main chunk
-    (see [relevant Webpack docs here](https://webpack.js.org/api/module-methods/#magic-comments)):
+2. Load all icons into a single chunk (do not split by size)
 
     ```ts
     import { Icons } from "@blueprintjs/icons";
 
-    // using the default dynamic loader, which uses Webpack's "lazy-once" mode
-    await Icons.loadAll();
+    Icons.setLoaderOptions({ loader: "all" });
 
-    // using a "simple" loader, which uses a dynamic import without any path arguments and thus does not require
-    // knowlege of any JS bundler specifics
-    await Icons.loadAll({ loader: "simple" });
+    // optionally, load the icons up-front so that future usage does not trigger a network request
+    await Icons.loadAll();
     ```
 
-2. Use static imports to load all icon paths statically (simpler, does not require knowledge of bundler specifics).
+3. Use a custom Webpack loader with "eager" mode to pull icon definitions into the main chunk.
+
+    This results in the largest bundle size for your main chunk.
 
     ```ts
-    import { Icons, getIconPaths } from "@blueprintjs/icons";
+    import { Icons, IconSize, IconPathsLoader } from "@blueprintjs/icons";
 
-    await Icons.loadAll({
-        loader: async (name, size) => getIconPaths(name, size),
-    });
+    const eagerLoader: IconPathsLoader = async (name, size) => {
+        return (
+            size === IconSize.STANDARD
+                ? await import(
+                    /* webpackChunkName: "blueprint-icons" */
+                    /* webpackInclude: /\.js$/ */
+                    /* webpackMode: "eager" */
+                    `@blueprintjs/icons/lib/esm/generated/16px/paths/${name}`
+                )
+                : await import(
+                    /* webpackChunkName: "blueprint-icons" */
+                    /* webpackInclude: /\.js$/ */
+                    /* webpackMode: "eager" */
+                    `@blueprintjs/icons/lib/esm/generated/20px/paths/${name}`
+                )
+        ).default;
+    };
+
+    Icons.setLoaderOptions({ loader: eagerLoader });
     ```
 
-3. Load all icons lazily, on-demand.
+4. Use a custom Webpack loader with "lazy" mode to load all icons lazily, on-demand.
 
     Any usage of `<Icon icon="..." />` will trigger a network request to fetch the individual icon contents chunk.
 
@@ -130,20 +144,19 @@ to its available APIs.
     await Icons.load(["download", "caret-down", "endorsed", "help", "lock"]);
     ```
 
-5. Custom loaders allow usage with other bundlers, like Vite for example.
+5. Use a custom loaders with other bundlers, for example Vite.
 
     ```ts
-    // specify a custom loader function for an alternative bundler, for example Vite
-    // see https://vitejs.dev/guide/features.html#glob-import
     import { Icons, IconPaths } from "@blueprintjs/icons";
 
+    // see https://vitejs.dev/guide/features.html#glob-import
     const iconModules: Record<string, { default: IconPaths[] }> =
         import.meta.glob([
             "../node_modules/@blueprintjs/icons/lib/esm/generated/16px/paths/*.js",
             "../node_modules/@blueprintjs/icons/lib/esm/generated/20px/paths/*.js",
         ]);
 
-    await Icons.loadAll({
+    Icons.setLoaderOptions({
         loader: async (name, size) => (
             iconModules[
                 `../node_modules/@blueprintjs/icons/lib/esm/generated/${size}px/paths/${name}.js`
diff --git a/packages/icons/src/paths-loaders/simplePathsLoader.ts b/packages/icons/src/paths-loaders/allPathsLoader.ts
similarity index 81%
rename from packages/icons/src/paths-loaders/simplePathsLoader.ts
rename to packages/icons/src/paths-loaders/allPathsLoader.ts
index 8ee76d71f4..d3059e82f6 100644
--- a/packages/icons/src/paths-loaders/simplePathsLoader.ts
+++ b/packages/icons/src/paths-loaders/allPathsLoader.ts
@@ -17,12 +17,12 @@
 import type { IconPathsLoader } from "../iconLoader";
 
 /**
- * A simple module loader for icon paths that does not require any knowledge of JS bundlers.
+ * A simple module loader which concatenates all icon paths into a single chunk.
  */
-export const simplePathsLoader: IconPathsLoader = async (name, size) => {
+export const allPathsLoader: IconPathsLoader = async (name, size) => {
     const { getIconPaths } = await import(
         /* webpackChunkName: "blueprint-icons-all-paths" */
-        "../iconPaths"
+        "../allPaths"
     );
     return getIconPaths(name, size);
 };
diff --git a/packages/icons/src/paths-loaders/splitPathsBySizeLoader.ts b/packages/icons/src/paths-loaders/splitPathsBySizeLoader.ts
new file mode 100644
index 0000000000..daa774fa0e
--- /dev/null
+++ b/packages/icons/src/paths-loaders/splitPathsBySizeLoader.ts
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { pascalCase } from "change-case";
+
+import type { IconPathsLoader } from "../iconLoader";
+import { IconName } from "../iconNames";
+import { IconPaths, IconSize } from "../iconTypes";
+import type { PascalCase } from "../type-utils";
+
+/**
+ * A dynamic loader for icon paths that generates separate chunks for the two size variants.
+ */
+export const splitPathsBySizeLoader: IconPathsLoader = async (name, size) => {
+    const key = pascalCase(name) as PascalCase<IconName>;
+    let pathsRecord: Record<PascalCase<IconName>, IconPaths>;
+
+    if (size === IconSize.STANDARD) {
+        pathsRecord = await import(
+            /* webpackChunkName: "blueprint-icons-16px-paths" */
+            "../generated/16px/paths"
+        );
+    } else {
+        pathsRecord = await import(
+            /* webpackChunkName: "blueprint-icons-20px-paths" */
+            "../generated/20px/paths"
+        );
+    }
+
+    return pathsRecord[key];
+};
diff --git a/packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts b/packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts
index 3a3ffc08f1..3f02942ec4 100644
--- a/packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts
+++ b/packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts
@@ -14,28 +14,28 @@
  * limitations under the License.
  */
 
-import type { IconPathsLoader } from "../iconLoader";
-import { IconSize } from "../iconTypes";
+// import type { IconPathsLoader } from "../iconLoader";
+// import { IconSize } from "../iconTypes";
 
-/**
- * The default icon paths loader, using webpack's "lazy-once" mode.
- *
- * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
- */
-export const webpackLazyOncePathsLoader: IconPathsLoader = async (name, size) => {
-    return (
-        size === IconSize.STANDARD
-            ? await import(
-                  /* webpackChunkName: "blueprint-icons-16px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "lazy-once" */
-                  `../generated/16px/paths/${name}`
-              )
-            : await import(
-                  /* webpackChunkName: "blueprint-icons-20px" */
-                  /* webpackInclude: /\.js$/ */
-                  /* webpackMode: "lazy-once" */
-                  `../generated/20px/paths/${name}`
-              )
-    ).default;
-};
+// /**
+//  * The default icon paths loader, using webpack's "lazy-once" mode.
+//  *
+//  * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
+//  */
+// export const webpackLazyOncePathsLoader: IconPathsLoader = async (name, size) => {
+//     return (
+//         size === IconSize.STANDARD
+//             ? await import(
+//                   /* webpackChunkName: "blueprint-icons-16px" */
+//                   /* webpackInclude: /\.js$/ */
+//                   /* webpackMode: "lazy-once" */
+//                   `../generated/16px/paths/${name}`
+//               )
+//             : await import(
+//                   /* webpackChunkName: "blueprint-icons-20px" */
+//                   /* webpackInclude: /\.js$/ */
+//                   /* webpackMode: "lazy-once" */
+//                   `../generated/20px/paths/${name}`
+//               )
+//     ).default;
+// };

From e1876c06990d930b5841937b279c7f9fcfda2015 Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Wed, 14 Jun 2023 13:36:22 -0400
Subject: [PATCH 8/9] Fix tests

---
 packages/icons/test/iconLoaderTests.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/icons/test/iconLoaderTests.ts b/packages/icons/test/iconLoaderTests.ts
index 17d352f031..6171049c91 100644
--- a/packages/icons/test/iconLoaderTests.ts
+++ b/packages/icons/test/iconLoaderTests.ts
@@ -2,8 +2,8 @@
  * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
  */
 
+import { getIconPaths } from "../src/allPaths";
 import { Icons } from "../src/iconLoader";
-import { getIconPaths } from "../src/iconPaths";
 
 describe("IconLoader", () => {
     it("is compatible with getIconPaths", () => {

From 9dd534adaa7cdb6ff7aac63dc8ec32db7430c903 Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Wed, 14 Jun 2023 13:37:17 -0400
Subject: [PATCH 9/9] Delete dead code

---
 .../webpackLazyOncePathsLoader.ts             | 41 -------------------
 1 file changed, 41 deletions(-)
 delete mode 100644 packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts

diff --git a/packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts b/packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts
deleted file mode 100644
index 3f02942ec4..0000000000
--- a/packages/icons/src/paths-loaders/webpackLazyOncePathsLoader.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-/*
- * Copyright 2023 Palantir Technologies, Inc. All rights reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-// import type { IconPathsLoader } from "../iconLoader";
-// import { IconSize } from "../iconTypes";
-
-// /**
-//  * The default icon paths loader, using webpack's "lazy-once" mode.
-//  *
-//  * @see https://webpack.js.org/api/module-methods/#magic-comments for dynamic import() reference
-//  */
-// export const webpackLazyOncePathsLoader: IconPathsLoader = async (name, size) => {
-//     return (
-//         size === IconSize.STANDARD
-//             ? await import(
-//                   /* webpackChunkName: "blueprint-icons-16px" */
-//                   /* webpackInclude: /\.js$/ */
-//                   /* webpackMode: "lazy-once" */
-//                   `../generated/16px/paths/${name}`
-//               )
-//             : await import(
-//                   /* webpackChunkName: "blueprint-icons-20px" */
-//                   /* webpackInclude: /\.js$/ */
-//                   /* webpackMode: "lazy-once" */
-//                   `../generated/20px/paths/${name}`
-//               )
-//     ).default;
-// };