feat(content): add recipe and tokens by thetaPC · Pull Request #31095 · ionic-team/ionic-framework

thetaPC · 2026-04-24T23:04:37Z

Issue number: resolves internal

What is the current behavior?

ion-content does not fragment styles based on themes. All 3 themes share one style. However, it's not configured to the Modular Ionic.

What is the new behavior?

Defined TypeScript Interface: Renamed content-interface.ts to content.interfaces.ts and added IonContentRecipe type.
Defined Theme Defaults: Added per-theme token defaults in ios, md, and ionic theme files.
Internal Variable Prefix: Renamed --offset-top / --offset-bottom to --internal-offset-top / --internal-offset-bottom to clearly separate them from the public CSS API.
CSS Logical Properties for RTL: Replaced physical-property RTL selectors on .transition-effect and .transition-shadow with the position-horizontal mixin.
Removed dead property: Dropped -webkit-overflow-scrolling: touch from styles as this property has been a no-op since iOS 13.
Updated Tests: Added unit specs for transitionShadow (present in ios mode, absent in md mode) and the getScrollElement() / getBackgroundElement() element ref methods.
New utility: Replaced inline new Promise((resolve) => componentOnReady(...)) patterns with a shared waitForComponent helper, reducing boilerplate and improving type safety.

Does this introduce a breaking change?

Yes
No

This PR introduces breaking changes to how ion-content is styled.

Migration Path:

CSS Variable Replacements: --background and --color have been removed. Use the new token structure:

--background -> IonContent.background
--color -> IonContent.color

--padding-* is still supported. .ion-padding, .ion-padding-* classes in css/padding.scss set --padding-* directly on the host. ion-content continues to honor those values (falling back to the new token when unset). Existing usage of the utility classes and direct --padding-* overrides will keep working.

New code is encouraged to use the token-based API instead:

--padding-top -> IonContent.padding.top
--padding-end -> IonContent.padding.end
--padding-bottom -> IonContent.padding.bottom
--padding-start -> IonContent.padding.start

Note: core/api.txt only lists the new --ion-content-padding-* variables. The --padding-* overrides remain functional but are no longer part of the documented public API.

If per-component customization is needed, the CSS variables can be used directly.

--background -> --ion-content-background
--color -> --ion-content-color
--padding-top -> --ion-content-padding-top
--padding-end -> --ion-content-padding-end
--padding-bottom -> --ion-content-padding-bottom
--padding-start -> --ion-content-padding-start

Internal-only variables (no replacement): The following CSS variables were previously documented @props on ion-content and have been renamed to the --internal-* namespace, removing them from the public API:

--keyboard-offset -> --internal-keyboard-offset
--offset-top      -> --internal-offset-top
--offset-bottom   -> --internal-offset-bottom

These are managed by ion-content itself (keyboard avoidance and header/footer offsets) and were never intended for consumer override. There is no replacement - any code that was setting them directly should be removed.

Theme classes: Remove any instances that target the theme classes: ion-content.md, ion-content.ios.

Other information

Previews:

The framework (Angular, React, Vue) test apps are not being styled correctly anymore because the new tokens are not being passed to them. This is expected until we can export the tokens as mentioned in the design doc. The functionality in those test apps are still working.

vercel · 2026-04-24T23:04:41Z

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

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	May 8, 2026 5:33pm

thetaPC · 2026-04-30T17:50:58Z

  flex-shrink: 2;
  overscroll-behavior-y: contain;
  overflow-y: auto;
-  -webkit-overflow-scrolling: touch;


-webkit-overflow-scrolling has become obsolete since iOS 13.

thetaPC · 2026-04-30T17:52:32Z

  contain: size style;
 }

-:host(.ion-color) .inner-scroll {


There seems to be a lot deleted, but they were just moved around in the file.

thetaPC · 2026-04-30T17:53:08Z

  @Method()
  async getBackgroundElement(): Promise<HTMLElement> {
    if (!this.backgroundContentEl) {
-      await new Promise((resolve) => componentOnReady(this.el, resolve));


Created a util for this since a lot of components are using the same code

thetaPC · 2026-05-05T13:42:01Z

+:host(.ion-color) .inner-scroll {
+  background: color.current-color(base);
+  color: color.current-color(contrast);
+}


I didn't make this customizable because all themes are using the same styles. If the community requests it, then we can update the recipe to include it.

What is this referring to?

thetaPC · 2026-05-05T13:48:22Z

 }

 .transition-shadow {
+  @include mixins.position-horizontal(null, 0);


We can now use this mixin instead of having to use left/right!

thetaPC · 2026-05-05T18:08:58Z


+:host(.ion-color) .inner-scroll {
+  background: color.current-color(base);
+  color: color.current-color(contrast);


I was going to switch this to use foreground as stated in the ticket but that lead to unwanted changes like:

The text color is not readable in some components. Others, it's too light and I question if it would pass accessibility.

We should look into the foreground values again.

The foreground color should only be used when it's a text-only component. So if setting color on the content changes its text but not its background. You can look at ion-text as an example of a text-only component that uses color. Since we are changing the background on this component, contrast is the correct text value.

ShaneK

Looking awesome! Mostly just have a few clarafication/documentation questions

ShaneK

Looks good to me! Just a question and a nit, but non-blocking

brandyscarney

Looking good! Minor changes requested.

brandyscarney · 2026-05-11T15:42:57Z

+  $padding-top: var(--padding-top, var(--ion-content-padding-top, 0px));
+  $padding-end: var(--padding-end, var(--ion-content-padding-end, 0px));
+  $padding-bottom: var(--padding-bottom, var(--ion-content-padding-bottom, 0px));
+  $padding-start: var(--padding-start, var(--ion-content-padding-start, 0px));


Why did we go this route instead of having the .ion-padding class set --ion-content-padding-top, --ion-content-padding-end, etc directly?

brandyscarney · 2026-05-12T21:13:20Z

+          customTheme: {
+            components: {
+              IonContent: {
+                background: '#f1f1f1',


How do we determine when this should be used over just keeping the css that was here and updating the variable?

<style> ion-content { --ion-content-background: #f1f1f1; } </style>

brandyscarney · 2026-05-12T21:15:12Z

 - Specific theme classes (e.g., `ion-chip.md`) are no longer supported. Style modifications based on the active theme must be implemented using theme tokens rather than direct class targeting.
 - The `border-radius` of the `ios` and `md` chip now defaults to `10px` and `8px`, respectively, instead of `16px` in accordance with the iOS and Material Design 3 guidelines. To revert to the previous appearance, set the `shape` to `"round"`, or override the `IonChip.shape.round.border.radius` to specify a different value for global styles and `--ion-chip-shape-round-border-radius` for component-specific styles.

+<h4 id="version-9x-content">Content</h4>


Could we clean this section up a bit? It's kind of hard to hard to read through. Maybe we can use a numbered list or dividers?

brandyscarney · 2026-05-12T21:20:33Z

+ * component readiness before accessing internal refs (e.g. in early lifecycle
+ * hooks like Vue onMounted with the custom elements build).
+ */
+export const waitForComponent = <T extends Element>(el: T): Promise<T> => {


Nit: should this be called waitForComponentReady?

brandyscarney · 2026-05-12T21:26:22Z

-  --offset-bottom: 0px;
-  --overflow: auto;
+  /**
+   * TODO(FW-6698): Remove this comment in v10.


Do we need this comment to begin with?

brandyscarney · 2026-05-12T21:29:21Z

+:host(.ion-color) .inner-scroll {
+  background: color.current-color(base);
+  color: color.current-color(contrast);
+}


What is this referring to?

brandyscarney · 2026-05-12T21:29:45Z


 .scroll-y {
-  overflow-y: var(--overflow);
+  overflow-y: var(--ion-content-overflow);


Should this fall back to auto?

brandyscarney · 2026-05-12T21:29:50Z


 .scroll-x {
-  overflow-x: var(--overflow);
+  overflow-x: var(--ion-content-overflow);


Should this fall back to auto?

brandyscarney · 2026-05-12T21:34:07Z


+:host(.ion-color) .inner-scroll {
+  background: color.current-color(base);
+  color: color.current-color(contrast);


The foreground color should only be used when it's a text-only component. So if setting color on the content changes its text but not its background. You can look at ion-text as an example of a text-only component that uses color. Since we are changing the background on this component, contrast is the correct text value.

brandyscarney · 2026-05-12T21:36:32Z

+  transform: translateZ(0);
+}
+
+// Content: iOS Mode Transition


Maybe we should add this on to FW-7295?

feat(content): add recipe and tokens

7afba1a

github-actions Bot added the package: core @ionic/core package label Apr 24, 2026

vercel Bot had a problem deploying to Preview April 24, 2026 23:05 Failure

thetaPC added 2 commits April 30, 2026 10:00

feat(content): cleanup

32d2fdb

feat(content): more cleanup

57c3140

github-actions Bot added the package: angular @ionic/angular package label Apr 30, 2026

vercel Bot deployed to Preview April 30, 2026 17:03 View deployment

refactor(utils): created waitForComponent

5983c3b

vercel Bot deployed to Preview April 30, 2026 17:37 View deployment

feat(styles): remove webkit-overflow-scrolling

76a32dd

vercel Bot deployed to Preview April 30, 2026 17:50 View deployment

thetaPC commented Apr 30, 2026

View reviewed changes

feat(content): improvements

7646ae6

vercel Bot deployed to Preview April 30, 2026 18:10 View deployment

feat(contenet): remove transition theme

412806f

vercel Bot deployed to Preview April 30, 2026 18:13 View deployment

refactor(contenet): update padding variables

c8f817c

vercel Bot deployed to Preview April 30, 2026 18:36 View deployment

vercel Bot deployed to Preview May 1, 2026 22:36 View deployment

vercel Bot deployed to Preview May 1, 2026 22:51 View deployment

vercel Bot deployed to Preview May 1, 2026 22:57 View deployment

github-actions Bot added the package: vue @ionic/vue package label May 1, 2026

vercel Bot deployed to Preview May 1, 2026 22:59 View deployment

vercel Bot deployed to Preview May 1, 2026 23:08 View deployment

thetaPC force-pushed the FW-6896 branch from 300abbf to c8f817c Compare May 4, 2026 13:22

github-actions Bot removed the package: vue @ionic/vue package label May 4, 2026

feat(content): remove unused config

6a496be

vercel Bot deployed to Preview May 5, 2026 13:40 View deployment

thetaPC commented May 5, 2026

View reviewed changes

thetaPC marked this pull request as ready for review May 5, 2026 15:37

thetaPC requested a review from a team as a code owner May 5, 2026 15:37

thetaPC requested a review from gnbm May 5, 2026 15:37

thetaPC marked this pull request as draft May 5, 2026 16:58

thetaPC commented May 5, 2026

View reviewed changes

thetaPC marked this pull request as ready for review May 5, 2026 18:09

ShaneK requested changes May 6, 2026

View reviewed changes

Comment thread core/src/components/content/content.scss

Comment thread core/src/css/core.scss Outdated

Comment thread core/src/components/content/content.scss

Comment thread core/src/components/content/content.scss Outdated

Comment thread core/src/themes/ios/default.tokens.ts Outdated

docs(content): add ion-padding comment

4704cc1

vercel Bot deployed to Preview May 6, 2026 22:56 View deployment

feat(content): use new token for menu global style

94e7f36

vercel Bot deployed to Preview May 6, 2026 22:58 View deployment

docs(content): add internal variables reason

dddcd4e

vercel Bot deployed to Preview May 6, 2026 23:10 View deployment

feat(content): add a fallback for font-family

095398c

vercel Bot deployed to Preview May 6, 2026 23:16 View deployment

docs(content): add Jira ticket to TODO

32ea3b7

vercel Bot deployed to Preview May 6, 2026 23:19 View deployment

thetaPC requested review from ShaneK and removed request for gnbm May 7, 2026 00:53

ShaneK approved these changes May 7, 2026

View reviewed changes

Comment thread core/src/global/config.ts Outdated

Comment thread core/src/components/content/content.scss

feat(config): clean up type

6f20e80

vercel Bot deployed to Preview May 8, 2026 13:26 View deployment

feat(content): remove right property

bc743b4

vercel Bot deployed to Preview May 8, 2026 13:39 View deployment

docs(BREAKING): add content

6337586

vercel Bot deployed to Preview May 8, 2026 17:33 View deployment

brandyscarney reviewed May 12, 2026

View reviewed changes

Conversation

thetaPC commented Apr 24, 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 Apr 24, 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!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ShaneK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

brandyscarney 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

thetaPC commented Apr 24, 2026 •

edited

Loading

vercel Bot commented Apr 24, 2026 •

edited

Loading