Skip to content

feat(label): convert to shadow DOM - #31657

Merged
brandyscarney merged 19 commits into
nextfrom
FW-7102
Nov 12, 2026
Merged

brandyscarney merged 19 commits into
nextfrom
FW-7102

Conversation

@brandyscarney

@brandyscarney brandyscarney commented Oct 26, 2026 •

Copy link
Copy Markdown
Member

Issue number: internal


What is the current behavior?

ion-label uses scoped encapsulation.

What is the new behavior?

  • Converts ion-label to Shadow DOM.
  • Label styles only reach direct children through ::slotted(), so heading and paragraph styles now apply to h1-h6 and p elements that are direct children of ion-label.
  • The global heading styles in typography.css and typography.ionic.css now skip headings that are direct children of ion-label, using selectors like h1:where(:not(ion-label > h1)) for each heading level, so the label's heading styles apply to them. The :where() keeps the original specificity.
  • Item now sets the size and margins of stacked, floating and fixed labels, because item's ::slotted(ion-label) styles take precedence over label's own styles in shadow DOM.
  • The disabled label opacity and the skeleton text overflow moved from label to item, because they depend on item state that changes after the label renders.
  • Label checks for an item parent with tag names instead of :host-context, which only Chromium supports in shadow DOM.
  • RTL uses the transform-origin mixin instead of a render-time label-rtl class.
  • Removes legacy :host-context rules for item classes that are no longer set (item-input, item-textarea, item-has-focus, item-has-value, item-has-placeholder), along with the focused and invalid color rules for stacked and floating labels.
  • Updates the component guide with a section on checking a parent's context in shadow components, and rewrites the RTL section to use logical properties, the RTL mixins, or isRTL() checked when needed, instead of render-time classes.

Does this introduce a breaking change?

  • Yes
  • No

BREAKING CHANGE:

ion-label has been converted to use Shadow DOM.

  • Default heading and paragraph styles only apply to h1-h6 and p elements that are direct children of ion-label. Nested headings, such as <ion-label><ion-text><h3>, no longer get label styles and get the global typography instead. Move ion-text inside the heading or paragraph, or set color on ion-label.
  • Global element styles such as h2 { font-size: 20px; } now take precedence over label's heading and paragraph styles. Scope them with h2:not(ion-label > h2) to keep the label styles.
  • App styles that target ion-label directly, such as a class that sets color, now take precedence over the default label styles.

Other information

@vercel

vercel Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

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

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

Request Review

@brandyscarney brandyscarney changed the title Fw 7102 feat(label): convert to shadow DOM Oct 26, 2026
@github-actions github-actions Bot added the package: core @ionic/core package label Oct 26, 2026
@brandyscarney brandyscarney changed the title feat(label): convert to shadow DOM feat(label): convert to shadow DOM Oct 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 3px comes from the markup change, not the shadow conversion. The h3 used to be the only child of ion-text, so iOS's h3:last-child { margin-bottom: 0 } applied. Shadow DOM can only style direct children, so it's now <h3><ion-text>…</ion-text></h3>. It's no longer a last child, so it keeps its 3px bottom margin. The scoped label renders this markup identically.

<ion-text color="primary">
<h3>H3 Title Text</h3>
</ion-text>
<h3><ion-text color="primary">H3 Title Text</ion-text></h3>

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In shadow DOM, label's ::slotted() styles only reach its direct children, so a heading nested inside ion-text loses label's heading styles and gets the global typography instead. Moving ion-text inside the heading keeps the h3 a direct child, so it still gets label's styles. This is documented in BREAKING.md.

:host(.ion-focused:not(.ion-color)) ::slotted(.label-stacked),
:host(.ion-focused:not(.ion-color)) ::slotted(.label-floating),
:host(.item-has-focus:not(.ion-color)) ::slotted(.label-stacked),
:host(.item-has-focus:not(.ion-color)) ::slotted(.label-floating) {

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The item-has-focus class was removed from item in v8 when we removed the legacy input support so these lines can be deleted:

:host(.label-floating) {
@include margin(null, null, 0, null);
@include transform(translate(0, 29px));
@include transform-origin(start, top);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was moved to label.scss.

:host(.label-floating) {
@include margin(0, 0, 0, 0);
/* stylelint-disable property-disallowed-list */
transform-origin: top left;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was moved to label.scss.

@ShaneK ShaneK left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally looks good, the conversion is really careful! The focused label color is the main one I'd like to see fixed, and I'm curious what you think about the CSS reset question. The rest are docs and nits.

Comment thread core/src/components/item/item.md.scss Resolved
Comment thread core/src/components/item/item.md.scss Resolved
Comment thread core/src/css/typography.scss Resolved
Comment thread docs/component-guide.md Resolved
Comment thread docs/component-guide.md Resolved
Comment thread core/src/components/label/label.md.scss Resolved
Comment thread core/src/components/label/label.tsx Resolved

@thetaPC thetaPC left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with Shane's comments, especially the focused color on colored labels and the floating labels with item-has-value.

Comment thread core/src/components/label/label.md.scss Resolved
Comment thread core/src/components/label/label.scss Resolved

@ShaneK ShaneK left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the updates, everything from my last review looks good! I left a few more comments, and the ionic focused color and the LTR-in-RTL label origin are the main ones.

Comment on lines +83 to +86
:host(.ion-focused) ::slotted(ion-label.label-floating),
:host(.item-has-value) ::slotted(ion-label.label-floating) {
@include globals.transform(translateY(50%), scale(0.75));
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:host(.ion-focused) ::slotted(ion-label.label-floating),
:host(.item-has-value) ::slotted(ion-label.label-floating) {
@include globals.transform(translateY(50%), scale(0.75));
}
:host(.ion-focused) ::slotted(ion-label.label-floating),
:host(.item-has-value) ::slotted(ion-label.label-floating) {
@include globals.transform(translateY(50%), scale(0.75));
}
:host(.ion-focused:not(.ion-color)) ::slotted(.label-stacked:not(.ion-color)),
:host(.ion-focused:not(.ion-color)) ::slotted(.label-floating:not(.ion-color)) {
color: globals.ion-color(primary, base);
}

The ionic theme lost the focused label color too. On next it shared the md label stylesheet, so a focused stacked or floating label turned primary (rgb(16, 92, 239)), and here it stays the default rgb(36, 37, 40). The md fix only went into item.md.scss, so I think it just needs the same rule here. With this the ionic labels match next in light and dark, and colored labels keep their color. The new focused label test says only md changes the color, so it could run ionic-md too.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:host(.label-stacked),
:host(.label-floating) {
@include margin(null, null, 0, null);
@include transform-origin(start, top);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is separate from the Safari case Maria raised. In Chromium, :host-context([dir=rtl]) matches any RTL ancestor, so an LTR section inside an RTL app (a <div dir="ltr"> in an <html dir="rtl"> page) now gets transform-origin: right top on md and ionic stacked and floating labels. At a 400px viewport that puts the label 92px to the right of where it sits on next, where isRTL() picked up the nearest dir="ltr" instead. The removed spec test covered exactly this case.

Could we bring back the label-rtl class from isRTL(this.el) for the origin? Or if we're fine with the new behavior, I think we should add an e2e for an LTR subtree in an RTL document so it's pinned either way.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the mixin instead: a0a9f42

Here is a before & after of the label:

Before After
label-item-stacked-ltr-in-rtl-md-rtl-Mobile-Chrome-linux label-item-stacked-ltr-in-rtl-md-rtl-Mobile-Chrome-linux

It also fixes popover's arrow so I can PR it into main.

Comment thread BREAKING.md

The default values for each heading, paragraph and theme are in [`label.scss`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/components/label/label.scss), [`label.ios.scss`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/components/label/label.ios.scss) and [`label.md.scss`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/components/label/label.md.scss).
- The global typography styles in `typography.css` no longer apply to headings that are direct children of `ion-label`. These headings are styled by `ion-label` instead.
- App styles that target `ion-label` directly now take precedence over the default `ion-label` styles. For example, a class that sets `color` on an `ion-label` inside of an `ion-item` previously had no effect because the label applied `var(--color)`, and it now changes the label color. Remove these styles if they are no longer wanted, or use the `--color` CSS variable to set the color of a label inside of an item.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- App styles that target `ion-label` directly now take precedence over the default `ion-label` styles. For example, a class that sets `color` on an `ion-label` inside of an `ion-item` previously had no effect because the label applied `var(--color)`, and it now changes the label color. Remove these styles if they are no longer wanted, or use the `--color` CSS variable to set the color of a label inside of an item.
- App styles that target `ion-label` directly now take precedence over the default `ion-label` styles. For example, a class that sets `color` on an `ion-label` inside of an `ion-item` previously had no effect because the label applied `var(--color)`, and it now changes the label color. Remove these styles if they are no longer wanted, or use the `--color` CSS variable to set the color of a label inside of an item.
- Stacked and floating labels in an item with the `ion-invalid` and `ion-touched` classes no longer use the `--highlight-color-invalid` CSS variable in the `md` and `ionic` themes. This only changes apps that set `--highlight-color-invalid` on `ion-item` or one of its ancestors. To keep the invalid color, add the following styles:
```css
ion-item:is(.md, .ionic).ion-invalid.ion-touched ion-label.label-stacked:not(.ion-color),
ion-item:is(.md, .ionic).ion-invalid.ion-touched ion-label.label-floating:not(.ion-color) {
color: var(--highlight-color-invalid);
}
```

The invalid label color rule was removed too. Nothing changes by default since Ionic never sets --highlight-color-invalid on the item, but apps that still set it on ion-item or :root will see touched invalid stacked and floating labels stop turning that color in md and ionic. Could we add a bullet for it? Up to you!

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread BREAKING.md Outdated

Complex selectors inside `:not()` require Chrome 88+, Firefox 84+ and Safari 9+, and `:where()` requires Chrome 88+, Firefox 78+ and Safari 14+.

This includes CSS resets such as Tailwind's Preflight and Bootstrap's Reboot. In v8, these resets did not change the headings and paragraphs inside `ion-label`, because the label styles took precedence. In v10, the reset takes precedence, so label headings and paragraphs lose their margins and use the reset's font size and weight. For example, with Tailwind's Preflight, `md` label headings render at `16px` with no margins instead of `24px`, `16px` and `14px`, and with Bootstrap's Reboot they render at `40px`, `32px` and `28px`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This includes CSS resets such as Tailwind's Preflight and Bootstrap's Reboot. In v8, these resets did not change the headings and paragraphs inside `ion-label`, because the label styles took precedence. In v10, the reset takes precedence, so label headings and paragraphs lose their margins and use the reset's font size and weight. For example, with Tailwind's Preflight, `md` label headings render at `16px` with no margins instead of `24px`, `16px` and `14px`, and with Bootstrap's Reboot they render at `40px`, `32px` and `28px`.
This includes CSS resets such as Tailwind's Preflight and Bootstrap's Reboot. In v9, these resets did not change the headings and paragraphs inside `ion-label`, because the label styles took precedence. In v10, the reset takes precedence, so label headings and paragraphs lose their margins and use the reset's font size and weight. For example, with Tailwind's Preflight, `md` label headings render at `16px` with no margins instead of `24px`, `16px` and `14px`, and with Bootstrap's Reboot they render at `40px`, `32px` and `28px`.

This should be v9, since label is still scoped there. That one's on me, my comment said v8 too.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

});
});

configs({ modes: ['ios', 'md', 'ionic-md'], directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
configs({ modes: ['ios', 'md', 'ionic-md'], directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {
/**
* The ios, md, and ionic themes each float the label
* with their own item styles, so this runs in all three.
*/
configs({ modes: ['ios', 'md', 'ionic-md'], directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {

Nit: the other two restricted blocks in this file explain their matrix, so this one could use a comment too. Up to you!

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@thetaPC thetaPC left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Comment thread BREAKING.md Resolved
@brandyscarney
brandyscarney merged commit 80a6ebb into next Nov 12, 2026
54 checks passed
@brandyscarney
brandyscarney deleted the FW-7102 branch November 12, 2026 20:41

This branch was successfully deployed

1 active deployment
Preview — f5a1e376 Deployed Nov 12, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

package: core @ionic/core package

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants