feat(router-link): add the link states from the ionic design by thetaPC · Pull Request #31707 · ionic-team/ionic-framework

thetaPC · 2026-11-06T03:47:29Z

Issue number: resolves internal

What is the current behavior?

ion-router-link has no pressed, visited or focus styles. The browser draws its own focus ring.

What is the new behavior?

In the ionic theme, links match the design kit:
- A link with no color turns #09358a when pressed or visited
- Pressed links are underlined
- A focused link shows a 2px #b5c0f7 ring with 4px corners
In the ios and md themes, a focused link shows a tinted background instead of the browser's ring, matching the clear button: the link's color at 12% opacity in md and 10% in ios, with padding that doesn't move the text
Adds tokens for each state: hue.<hue>.activated.color, hue.<hue>.visited.color and hue.<hue>.focus.background (also under semantic), state.focus.ring, state.focus.border.radius, state.focus.padding, and text.decoration, which state.activated and state.focus can override
A state token a theme leaves unset uses the link's resting value
Adds a states test page and screenshot test

Does this introduce a breaking change?

Yes
No

Focus style: in ios and md, a focused router link now shows a tinted background instead of the browser's default ring. Customize it with the tokens for global styles, or the CSS variables for component-specific styles:

Property	Token (global)	CSS variable (component-specific)
Background	`IonRouterLink.hue.bold.focus.background`	`--ion-router-link-hue-bold-focus-background`
Background, `color` set	`IonRouterLink.hue.bold.semantic.focus.background`	`--ion-router-link-hue-bold-semantic-focus-background`
Corner radius	`IonRouterLink.state.focus.border.radius`	`--ion-router-link-state-focus-border-radius`
Padding	`IonRouterLink.state.focus.padding`	`--ion-router-link-state-focus-padding-top`, `-end`, `-bottom`, `-start`

Other information

Focus style in ios and md

Neither theme has a design for a focused link, and they can't keep the browser's ring, because the rule that draws the ionic ring turns it off in every theme. Both follow MD2's clear button, which shows focus as a tinted background, and reuse the button's clear focus values. A theme can set the ring, the background or both, so a future MD3 theme can show a ring through tokens alone.

Known gaps

Visited links aren't underlined in the ionic theme, although the design kit shows an underline. Browsers only allow color changes on :visited to protect browsing history, so text-decoration there is ignored. Visited links still get the darker color
In the ionic theme, links with color set keep their color when pressed or visited. The kit only shows the primary link, and the palette has no darker variant to use

How to test

The states page is new, so Before points at the basic page.

Check	Before	After	What to look for
States, ionic	Before	After	Focused: light blue ring. Activated: darker and underlined. Visited: darker, no underline
Focus style, md	Before	After	Before: Tab to a link for the browser's ring. After: the Focused row has a light primary background, and red behind Danger
Focus style, ios	Before	After	Same as md

vercel · 2026-11-06T03:47:34Z

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

Project	Deployment	Actions	Updated
ionic-framework	Ready	Preview	Nov 12, 2026 11:26pm UTC

thetaPC · 2026-11-06T03:53:03Z

If we're not a fan of the focus ring, I would vote in creating a follow up PR so we can investigate what values to use by looking into MD2 and iOS native components.

Material Design 2 uses a background on focus on their clear buttons:

Material Design 3 seems to use a ring for their "text" buttons:

I think we should probably match MD2 for the initial MD theme that is added then support the ring when we add MD3 support. We might want to make this configurable?

I am fine with this being a follow-up ticket.

Thanks for the references! Changed md and ios to match MD2 in 78b2a24: a focused link now gets a tinted background like the clear button (the link's color at 12% in md, 10% in ios), with a bit of padding that doesn't move the text. The ring is still there for ionic, and a theme can set the ring, the background or both through tokens, so MD3 can switch to the ring without code changes.

brandyscarney

Left some non-blocking questions. 👍

brandyscarney · 2026-11-09T22:57:50Z

Material Design 2 uses a background on focus on their clear buttons:

Material Design 3 seems to use a ring for their "text" buttons:

I think we should probably match MD2 for the initial MD theme that is added then support the ring when we add MD3 support. We might want to make this configurable?

I am fine with this being a follow-up ticket.

# Conflicts: # BREAKING.md # core/api.txt # core/src/components/router-link/router-link.scss

brandyscarney

LGTM!

ShaneK

Looks good to me! Just a few small things, the subtle hue one is probably the main one.

ShaneK · 2026-11-11T20:00:17Z

      hue: {
        bold: {
+          activated: {
+            color: '#09358a',


Since #09358a is hardcoded here and the ionic dark palette doesn't override it, a pressed or visited link would be around 1.9:1 once dark gets a real dark background. It doesn't affect anything today because ionic's dark palette is still a placeholder with a white page, so this is just something to keep in mind for FW-7558. No action required.

Good catch, I'll keep it in mind when the ionic dark palette gets its real background.

ShaneK · 2026-11-11T20:01:55Z

@@ -945,6 +953,35 @@ export const defaultTheme: DefaultTheme = {
          },


Was leaving activated and visited off subtle on purpose? Right now a pressed subtle link underlines but stays #004acd, while a bold link that looks the same at rest turns #09358a, and visited subtle links keep the resting color too. Adding the same activated and visited colors under hue.subtle makes them match.

Not on purpose, thanks! Added them in df3ed27, so subtle pressed and visited links now match bold.

ShaneK · 2026-11-11T20:04:29Z

+/**
+ * This behavior does not vary across directions.
+ */
+configs({ modes: ['ios', 'md', 'ionic-md'], directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {


This only renders the default bold hue, but every state rule is generated for subtle too. Adding some hue="subtle" links, like chip/test/states does, would catch the subtle pressed color I mentioned on the ionic tokens. The test/states/index.html page would need them too.

Added subtle links to the test and to test/states/index.html in bf1b63b.

ShaneK · 2026-11-11T20:06:22Z

 a {
  @include mixins.text-inherit();
+
+  // The focus ring below replaces the browser's own ring


Suggested change

// The focus ring below replaces the browser's own ring

// The theme's focus ring or background below replaces the browser's own ring

The md and ios themes don't set any ring tokens, so the tinted background is what shows focus there. I'd also rename the should be focusable for the focus ring spec to something like should add the ion-focusable class for the same reason.

Done, and renamed the spec in 9bfc96b.

ShaneK · 2026-11-11T20:10:07Z

+ * @prop --ion-router-link-state-focus-padding-bottom: Bottom padding of the focus background
+ * @prop --ion-router-link-state-focus-padding-end: End padding of the focus background
+ * @prop --ion-router-link-state-focus-padding-start: Start padding of the focus background
+ * @prop --ion-router-link-state-focus-padding-top: Top padding of the focus background


Suggested change

* @prop --ion-router-link-state-focus-padding-bottom: Bottom padding of the focus background

* @prop --ion-router-link-state-focus-padding-end: End padding of the focus background

* @prop --ion-router-link-state-focus-padding-start: Start padding of the focus background

* @prop --ion-router-link-state-focus-padding-top: Top padding of the focus background

* @prop --ion-router-link-state-focus-padding-bottom: Bottom padding of the focus ring and background

* @prop --ion-router-link-state-focus-padding-end: End padding of the focus ring and background

* @prop --ion-router-link-state-focus-padding-start: Start padding of the focus ring and background

* @prop --ion-router-link-state-focus-padding-top: Top padding of the focus ring and background

The ionic theme has no focus background, so these only size the ring there. This matches the border-radius prop's wording.

Done in 2e8c726.

ShaneK · 2026-11-11T20:11:51Z

 3. The color applied by the `color` prop is now driven by the centralized Ionic Theming system, scoped to the new `hue` property. <sup>[3](#version-10x-router-link-hue)</sup>
 4. The text color now uses the color's `foreground` variant instead of `base`. <sup>[4](#version-10x-router-link-foreground)</sup>
-5. Mode classes (`ion-router-link.md`, `ion-router-link.ios`) are no longer supported. <sup>[5](#version-10x-router-link-mode-classes)</sup>
+5. A focused router link now shows a tinted background instead of the browser's focus ring. <sup>[5](#version-10x-router-link-focus)</sup>


Suggested change

5. A focused router link now shows a tinted background instead of the browser's focus ring. <sup>[5](#version-10x-router-link-focus)</sup>

5. In the `md` and `ios` themes, a focused router link now shows a tinted background instead of the browser's focus ring. In the `ionic` theme, it shows a 2px ring. <sup>[5](#version-10x-router-link-focus)</sup>

Right now this reads like ionic gets a tinted background too, but it draws a 2px ring with no background. The main sentence in the Focus style section has the same problem.

Updated the list item and the Focus style paragraph in 9066e4a.

ShaneK · 2026-11-11T20:14:13Z

+  test.describe(title('router-link: states'), () => {
+    test('should not have visual regressions', async ({ page }) => {
+      /**
+       * The padding keeps the focus ring, which sits outside the


Nit: these comments are a lot heavier than the other router-link tests. I think the CSS ones could each be a single line, and the empty href note is already in test/states/index.html. The Firefox note is useful though, so I'd keep that one. No worries if you don't want to do that.

Shortened them in e737edd and kept the Firefox note.

…o bold Co-authored-by: Shane <[email protected]>

Co-authored-by: Shane <[email protected]>

feat(router-link): add the link states from the ionic design

2286821

thetaPC added this pull request to stack #31706 November 6, 2026 03:47

github-actions Bot added the package: core @ionic/core package label Nov 6, 2026

vercel Bot deployed to Preview November 6, 2026 03:47

View deployment

test(router-link): screenshot the visited state

fecb088

thetaPC commented Nov 6, 2026

View reviewed changes

vercel Bot deployed to Preview November 6, 2026 03:56

View deployment

thetaPC marked this pull request as ready for review November 6, 2026 04:07

thetaPC requested a review from a team as a code owner November 6, 2026 04:07

thetaPC requested a review from brandyscarney November 6, 2026 04:07

brandyscarney approved these changes Nov 9, 2026

View reviewed changes

Merge remote-tracking branch 'origin/FW-6903' into FW-6903-ionic-spec

9c4ac32

# Conflicts: # BREAKING.md # core/api.txt # core/src/components/router-link/router-link.scss

vercel Bot deployed to Preview November 10, 2026 18:14

View deployment

feat(router-link): show a tinted background on focus in md and ios

78b2a24

vercel Bot deployed to Preview November 10, 2026 19:12

View deployment

fix(router-link): fit the ionic focus ring to the design

502cfdf

vercel Bot deployed to Preview November 10, 2026 19:47

View deployment

brandyscarney approved these changes Nov 11, 2026

View reviewed changes

Comment thread core/src/components/router-link/router-link.interface.ts Resolved

refactor(router-link): group visited with the other states

52d6a28

vercel Bot deployed to Preview November 11, 2026 19:24

View deployment

ShaneK approved these changes Nov 11, 2026

View reviewed changes

thetaPC and others added 7 commits November 11, 2026 19:52

Merge remote-tracking branch 'origin/FW-6903' into FW-6903-ionic-spec

3bb116c

fix(router-link): match the ionic subtle pressed and visited colors t…

df3ed27

…o bold Co-authored-by: Shane <[email protected]>

test(router-link): screenshot the subtle hue states

bf1b63b

Co-authored-by: Shane <[email protected]>

docs(router-link): say the focus style can be a ring or a background

9bfc96b

Co-authored-by: Shane <[email protected]>

docs(router-link): say the focus padding sizes the ring too

2e8c726

Co-authored-by: Shane <[email protected]>

docs(router-link): describe the ionic focus ring in BREAKING

9066e4a

Co-authored-by: Shane <[email protected]>

test(router-link): shorten the states test comments

e737edd

Co-authored-by: Shane <[email protected]>

vercel Bot deployed to Preview November 12, 2026 03:57

View deployment

Merge remote-tracking branch 'origin/FW-6903' into FW-6903-ionic-spec

5f8ec74

vercel Bot deployed to Preview November 12, 2026 22:02

View deployment

Merge branch 'FW-6903' into FW-6903-ionic-spec

bd5eff5

vercel Bot deployed to Preview November 12, 2026 23:26

View deployment

thetaPC merged commit d25d9e4 into ionic-modular Nov 12, 2026
54 checks passed

thetaPC deleted the FW-6903-ionic-spec branch November 12, 2026 23:40

		@@ -945,6 +953,35 @@ export const defaultTheme: DefaultTheme = {
		},

	// The focus ring below replaces the browser's own ring
	// The theme's focus ring or background below replaces the browser's own ring

	5. A focused router link now shows a tinted background instead of the browser's focus ring. <sup>[5](#version-10x-router-link-focus)</sup>
	5. In the `md` and `ios` themes, a focused router link now shows a tinted background instead of the browser's focus ring. In the `ionic` theme, it shows a 2px ring. <sup>[5](#version-10x-router-link-focus)</sup>

Conversation

thetaPC commented Nov 6, 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

Focus style in ios and md

Known gaps

How to test

Uh oh!

vercel Bot commented Nov 6, 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!

thetaPC Nov 10, 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!

brandyscarney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brandyscarney left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ShaneK left a comment

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!

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!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

thetaPC commented Nov 6, 2026 •

edited

Loading

vercel Bot commented Nov 6, 2026 •

edited

Loading

thetaPC Nov 10, 2026 •

edited

Loading