feat(config): add icon options and align ionic theme with md defaults by brandyscarney · Pull Request #31418 · ionic-team/ionic-framework

brandyscarney · 2026-09-02T18:16:56Z

Issue number: internal

What is the current behavior?

Several components use Phosphor Icons by default only for the ionic theme.

What is the new behavior?

Removes the Phosphor Icon defaults for the ionic theme, instead replacing them with whatever icon md uses
This reverts most of the code in 08fc0b9
Phosphor Icon svgs can be set directly by any app consuming Ionic Framework using the config, or passed to ion-icon as a font.
Adds the missing config properties for icons which were removed:
- Checkbox: checkboxCheckedIcon and checkboxIndeterminateIcon
- Refresher: refresherArrowIcon
- Select Modal: selectModalCancelIcon

Does this introduce a breaking change?

Yes
No

The ionic theme is unreleased so none of what is being removed was ever in the public API. This is for the next major version of Ionic.

Other information

Previews:

vercel · 2026-09-02T18:17:03Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
ionic-framework	Ready	Preview	Sep 17, 2026 7:45pm UTC

brandyscarney · 2026-09-14T21:57:50Z

The default icons have changed for the ionic theme, so all of these screenshot diffs are expected.

…IndeterminateIcon

brandyscarney · 2026-09-15T20:49:45Z

 .native-wrapper {
+  @include mixins.border-radius(var(--border-radius));
+
  display: flex;

+  position: relative;
+
+  flex-shrink: 0;
+
  align-items: center;
+
+  width: var(--size);
+  height: var(--size);
+
+  transition: var(--transition);
+
+  border-width: var(--border-width);
+  border-style: var(--border-style);
+  border-color: var(--border-color);
+
+  background: var(--checkbox-background);
+
+  box-sizing: border-box;
 }


These styles were the same in the ionic and native files so I moved them to common.

brandyscarney · 2026-09-15T20:51:39Z

  --border-color: #{globals.$ion-primitives-neutral-800};
-  --checkmark-width: #{globals.$ion-scale-400};
-  --checkmark-height: var(--checkmark-width);
+  --checkmark-width: 3;


This matches md theme and makes it so all themes are consistently styled.

brandyscarney · 2026-09-15T20:52:11Z

 .native-wrapper {
-  @include globals.border-radius(var(--border-radius));
-
-  flex-shrink: 0;
-
  justify-content: center;
-
-  width: var(--size);
-  height: var(--size);
-
-  transition: var(--transition);
-
-  border-width: var(--border-width);
-  border-style: var(--border-style);
-  border-color: var(--border-color);
-
-  background: var(--checkbox-background);
-
-  box-sizing: border-box;
 }


These styles were the same in the ionic and native files so I moved them to common.

brandyscarney · 2026-09-15T20:58:57Z

-            >
-              {path}
-            </svg>
+          <div class="native-wrapper" part="container">


I moved the container part to the element wrapping the icon rather than the svg so that the default checkmark and a custom configured icon can be styled consistently. I didn't notice any visual differences when comparing the styles in the docs demo, but this could be a breaking change for anyone targeting the icon specifically as an svg. If the reviewers agree, I can add this to the breaking changes document.

brandyscarney · 2026-09-15T20:59:59Z

+              checkmark CSS properties. An icon set in the config replaces the
+              slotted path, so both are styled through the same element.
+            */}
+            <ion-icon class="checkbox-icon" icon={markIcon} part="icon" aria-hidden="true">


I decided to wrap the default checkmark svg in an ion-icon container so that developers can override the default or a custom configured icon the same way:

ion-checkbox::part(icon) { color: red; }

brandyscarney · 2026-09-15T21:02:43Z

-.checkbox-icon {
-  @include border-radius(var(--border-radius));
-
-  width: var(--size);
-  height: var(--size);
-
-  transition: var(--transition);
-
-  border-width: var(--border-width);
-  border-style: var(--border-style);
-  border-color: var(--border-color);
-
-  background: var(--checkbox-background);
-
-  box-sizing: border-box;
-}


These styles were moved to the .native-wrapper, making them the same in the ionic and native files so I moved them to common.

brandyscarney · 2026-09-15T21:04:58Z

The --checkmark-width now applies the same for all themes, making this have a custom stroke width.

brandyscarney · 2026-09-15T21:05:46Z

The --size now applies the same for all themes, making this have a custom checkmark size.

… into FW-6998

ShaneK

Really nice cleanup, great work! Two things I'd like to sort out before this goes in.

The new custom icon test reassigns window.Ionic, which drops the mode and theme that setContent injects, so all three of its matrix entries are rendering as md and the ios and ionic baselines aren't testing what they look like they're testing. Separately, ion-alert still has the Phosphor checkmark inlined in its ionic branch, so that's the one spot where the acceptance criteria aren't met yet.

Everything else is nits and a couple of coverage gaps, take or leave those.

ShaneK

Really nice cleanup, the getter consolidation and the scss hoisting both look great.

One thing worries me and that's the main holdup, the rest is nits.

ShaneK · 2026-09-18T13:41:09Z

+            <ion-icon class="checkbox-icon" icon={markIcon} part="icon" aria-hidden="true">
+              {!markIcon && <svg viewBox="0 0 24 24">{path}</svg>}


This seems like a big issue, and it comes out of my flicker nit last round, so sorry for sending you down this path.

Gating the svg on !markIcon means a configured icon never gets replaced by the theme's mark. The ion-icon renders its <slot> only while its resolved svg content is empty, and ionicons never clears that content when icon goes away, so once it has loaded anything the slot is gone for good.

You don't need a programmatic change to hit it. Set only checkboxIndeterminateIcon, render an indeterminate checkbox, and one user click leaves the indeterminate icon painted on a now-checked box. With that config the icon renders in every state including checked, so the theme checkmark never appears at all.

Adding a key so the element gets replaced when the mark switches kind fixes it:

Suggested change

<ion-icon class="checkbox-icon" icon={markIcon} part="icon" aria-hidden="true">

{!markIcon && <svg viewBox="0 0 24 24">{path}</svg>}

<ion-icon

key={markIcon ? 'config-icon' : 'theme-mark'}

class="checkbox-icon"

icon={markIcon}

part="icon"

aria-hidden="true"

>

{!markIcon && <svg viewBox="0 0 24 24">{path}</svg>}

</ion-icon>

That holds up across all three config permutations, and with nothing configured the output is identical to what's here now, so the baselines aren't affected. Always rendering the svg and hiding it with CSS doesn't work, since the slot never comes back once it's gone.

Neither new test catches it, since newSpecPage doesn't hydrate ion-icon and the custom icon spec always sets both keys.

ShaneK · 2026-09-18T13:41:26Z

  /**
   * @prop --size: Size of the checkbox icon
   *
+   * @prop --checkbox-background: Background of the checkbox icon


One for the @prop --checkmark-width: Stroke width of the checkbox checkmark line just below, which didn't get the caveat @part mark did.

Setting it does nothing once an icon is set in the config, since it only applies through .checkbox-icon path and can't reach an icon rendering inside the ion-icon shadow root. With --checkmark-width: 10 the stroke comes out 10px without a config icon and 1px with one. The color prop is fine, since that one goes on the host and ionicons picks it up from currentColor.

The same clause you put on @part mark would cover it.

ShaneK · 2026-09-18T13:41:27Z

 * @part label - The label text describing the checkbox.
- * @part mark - The checkmark used to indicate the checked state.
+ * @part icon - The icon that displays the checked or indeterminate mark.
+ * @part mark - The checkmark used to indicate the checked state. Only applies when no icon is set in the config.


Suggested change

* @part mark - The checkmark used to indicate the checked state. Only applies when no icon is set in the config.

* @part mark - The mark used to indicate the checked or indeterminate state. Only applies when no icon is set in the config.

You widened the icon part to cover both states, and this one still says checked only, but part="mark" is on both branches of getSVGPath for every theme including the indeterminate paths. Someone styling the indeterminate dash would read the part table and think it doesn't apply. The config caveat is right.

ShaneK · 2026-09-18T13:41:31Z

+   * Otherwise, use the icon set in the config.
+   * If no icon is set in the config, use the default icon.
+   */
  get backButtonIcon() {


This getter and eight others got the JSDoc treatment but kept a bare signature, so they infer any out of config.get instead of string. The guide section you added shows the annotated form and the other icon getters in core already have it.

There's one catch before you add them, though. Annotating this one breaks the build, since hasIconOnly just below returns this.backButtonIcon && !this.backButtonText and only type-checked while the getter was any. That means changing it to get hasIconOnly(): boolean with a !! on the first operand. The coercion changes no result, so it's two files rather than a one-liner. Up to you whether that belongs here or separately.

ShaneK · 2026-09-18T13:41:32Z

-            >
-              {path}
-            </svg>
+          <div class="native-wrapper" part="container">


Yeah, I think this should go in the breaking changes doc, since it's a v9 part rather than the unreleased theme. Anything setting fill or stroke through it stops working, and ::part(container) > * now hits a different element.

brandyscarney added 3 commits September 2, 2026 14:08

refactor(many): remove phosphor icon usage

7057225

chore(deps): remove @phosphor-icons/core

69200e8

chore: remove old svgTransform for Jest

4023d2a

github-actions Bot added the package: core @ionic/core package label Sep 2, 2026

vercel Bot deployed to Preview September 2, 2026 18:24 View deployment

style: add consistent comments to the icon getters

d5c3159

vercel Bot deployed to Preview September 14, 2026 21:06 View deployment

brandyscarney added 2 commits September 14, 2026 17:27

feat(config): add option to override selectModalCancelIcon

662509c

feat(config): add option to override refresherArrowIcon

ccf41e1

brandyscarney changed the title ~~refactor(many): remove Phosphor Icon defaults from the ionic theme~~ feat(config): add icon options and align ionic theme with md defaults Sep 14, 2026

vercel Bot deployed to Preview September 14, 2026 21:47 View deployment

chore(): add updated snapshots

9882ad6

brandyscarney commented Sep 14, 2026

View reviewed changes

vercel Bot deployed to Preview September 14, 2026 22:03 View deployment

feat(config): add option to override checkboxCheckedIcon and checkbox…

a675914

…IndeterminateIcon

vercel Bot deployed to Preview September 15, 2026 20:33 View deployment

chore(): add updated snapshots

55b217c

brandyscarney commented Sep 15, 2026

View reviewed changes

vercel Bot deployed to Preview September 15, 2026 20:50 View deployment

brandyscarney commented Sep 15, 2026

View reviewed changes

brandyscarney marked this pull request as ready for review September 15, 2026 21:13

brandyscarney requested a review from a team as a code owner September 15, 2026 21:13

brandyscarney requested a review from OS-jacobbell September 15, 2026 21:13

brandyscarney requested review from ShaneK and removed request for OS-jacobbell September 15, 2026 21:20

brandyscarney added 2 commits September 15, 2026 17:42

docs(component-guide): add a section on icon global config

403df5d

Merge branch 'FW-6998' of https://github.com/ionic-team/ionic-framework…

c591b44

… into FW-6998

vercel Bot deployed to Preview September 15, 2026 21:51 View deployment

ShaneK requested changes Sep 16, 2026

View reviewed changes

style(checkbox): update docs, styles, destructure props

57cadbf

vercel Bot deployed to Preview September 16, 2026 20:43 View deployment

test(checkbox): set config properly to not override mode

550e889

vercel Bot deployed to Preview September 16, 2026 20:54 View deployment

style: rename select-modal getter and remove return comments

861c01c

vercel Bot deployed to Preview September 16, 2026 21:03 View deployment

brandyscarney added 2 commits September 16, 2026 17:46

style: update refresher comments

fddf4eb

refactor(alert): remove inline Phosphor icon in ionic theme

393a0bc

vercel Bot deployed to Preview September 16, 2026 22:38 View deployment

test(checkbox): add ionic theme to the indeterminate test

8b271d6

vercel Bot deployed to Preview September 16, 2026 22:46 View deployment

refactor(checkbox): don't require calculations on icon

73ce038

vercel Bot deployed to Preview September 16, 2026 23:01 View deployment

fix(checkbox): only render the svg if markIcon is not set

badfb51

vercel Bot deployed to Preview September 17, 2026 16:03 View deployment

test(checkbox): add additional coverage for ionic theme

d513494

vercel Bot deployed to Preview September 17, 2026 19:45 View deployment

brandyscarney requested a review from ShaneK September 17, 2026 20:15

ShaneK requested changes Sep 18, 2026

View reviewed changes

		<ion-icon class="checkbox-icon" icon={markIcon} part="icon" aria-hidden="true">
		{!markIcon && <svg viewBox="0 0 24 24">{path}</svg>}

	* @part mark - The checkmark used to indicate the checked state. Only applies when no icon is set in the config.
	* @part mark - The mark used to indicate the checked or indeterminate state. Only applies when no icon is set in the config.

Conversation

brandyscarney commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Other information

Uh oh!

vercel Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ShaneK left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

brandyscarney commented Sep 2, 2026 •

edited

Loading

vercel Bot commented Sep 2, 2026 •

edited

Loading

ShaneK left a comment •

edited

Loading

ShaneK left a comment •

edited

Loading

ShaneK Sep 18, 2026 •

edited

Loading