docs(select): add new section on rich content options by brandyscarney · Pull Request #4512 · ionic-team/ionic-docs

brandyscarney · 2026-05-20T15:47:29Z

Adds the following:

Select documentation for the new feature allowing HTML to be passed to select options.
Adds a new property to Playground called ionicConfig which allows you to pass config options that get merged with mode in the Playground example.

vercel · 2026-05-20T15:47:37Z

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

Project	Deployment	Actions	Updated (UTC)
ionic-docs	Ready	Preview, Comment	May 22, 2026 5:22pm

brandyscarney · 2026-05-20T16:58:50Z

+   * example: `{ innerHTMLTemplatesEnabled: true }`. Merges with the active
+   * preview `mode` when opening the editor.
+   */
+  ionicConfig?: IonicConfig;


I decided to add this as a config object instead of adding innerHTMLTemplatesEnabled as a boolean because this will allow us to enhance the Config documentation if desired by adding playgrounds passing different config options.

I don't mind this, but my concern is that it might be confusing for devs who are reviewing the demos. Some might not realize the important admonition and only copy/paste code. They'll probably think that the select option has a bug. If we included innerHTMLTemplatesEnabled within the code then we can avoid this.

I don't feel strongly about this since:

you do have that admonition

the demos only provide the bare minimal (meaning we don't show files like App.tsx to showcase config changes)

brandyscarney · 2026-05-20T16:59:16Z

+ * Ionic app configuration. See [IonicConfig](/docs/developing/config#ionicconfig).
+ * Playground only injects serializable values (string, number, boolean) into StackBlitz.
+ */
+export type IonicConfig = Record<string, unknown>;


I was going to import the type from Ionic but then we would have a dependency on @ionic/core and I don't know if we want that.

brandyscarney · 2026-05-20T17:06:04Z

+
+## Ionic Config
+
+Pass an [IonicConfig](/docs/developing/config#ionicconfig) object so generated StackBlitz projects bootstrap with the same settings. This is merged with the active preview `mode` when opening the editor. Only string, number, and boolean values are injected into generated code:


I chose this rather than adding an entire file for each framework to pass the config like Vue but if we prefer that approach I can revert this.

brandyscarney · 2026-05-20T17:08:29Z

+  const formatInterfaceLabel = (selectInterface) => {
+    return selectInterface
+      .split('-')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  };
+
+  /* Dynamically create the different Select components */
+  const selectInterfaces = ['alert', 'action-sheet', 'modal', 'popover'];


Originally I defined the interface array like this:

const selectInterfaces = [{ label: 'Alert', value: 'alert', }, { label: 'Action Sheet', value: 'action-sheet', }, { label: 'Modal', value: 'modal', }, { label: 'Popover', value: 'popover', }];

but I removed it in favor of using the single string and converting it to the label. If we think this is too much for the demo, I can go back to the object array.

brandyscarney · 2026-05-20T17:08:58Z

+    /* The interfaceOptions property is for demonstration purposes only. */
+    /* It is not required for the rich options to work. */
+    select.interfaceOptions = {
+      header: 'Travel mode',
+    };


This is just to make the demo look nicer but can be removed if desired.

thetaPC

LGTM, minor suggestions!

Thank you for updating the Playground docs!

thetaPC · 2026-05-22T13:46:35Z


 <StartEndSlots />

+## Rich Content Options


It should also mention that a selected text will strip out the HTML to only provide plain text. Also start, end slots and descriptions are not included.

thetaPC · 2026-05-22T13:49:45Z


+## Rich Content Options
+
+:::important


Not part of this PR but personal question: Do you think purple is appropriate for important?

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

+## Rich Content Options
+
+:::important
+Rich content in select options is disabled by default. Set [`innerHTMLTemplatesEnabled`](/docs/developing/config#ionicconfig) to `true` in your [global Ionic config](/docs/developing/config#global-config). Markup inside options is treated as plain text when it is disabled. Refer to [Security](/docs/techniques/security.md) for sanitization guidance when enabling custom HTML.


By adding .md, it will be easier to migrate the files later from .md to .mdx.

Suggested change

Rich content in select options is disabled by default. Set [`innerHTMLTemplatesEnabled`](/docs/developing/config#ionicconfig) to `true` in your [global Ionic config](/docs/developing/config#global-config). Markup inside options is treated as plain text when it is disabled. Refer to [Security](/docs/techniques/security.md) for sanitization guidance when enabling custom HTML.

Rich content in select options is disabled by default. Set [`innerHTMLTemplatesEnabled`](/docs/developing/config.md#ionicconfig) to `true` in your [global Ionic config](/docs/developing/config.md#global-config). Markup inside options is treated as plain text when it is disabled. Refer to [Security](/docs/techniques/security.md) for sanitization guidance when enabling custom HTML.

thetaPC · 2026-05-22T13:52:07Z

 ## Enabling Custom HTML Parsing via `innerHTML`

-`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, and `ion-toast` can accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. This behavior is disabled by default which means values passed to the affected components will always be interpreted as plaintext. Developers can enable this custom HTML behavior by setting `innerHTMLTemplatesEnabled: true` in the [IonicConfig](../developing/config#ionicconfig).
+`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-select-option`, and `ion-toast` can accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. This behavior is disabled by default which means values passed to the affected components will always be interpreted as plaintext. Developers can enable this custom HTML behavior by setting `innerHTMLTemplatesEnabled: true` in the [IonicConfig](../developing/config#ionicconfig).


By adding .md, it will be easier to migrate the files later from .md to .mdx. Might as well add it since we're here.

Suggested change

`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-select-option`, and `ion-toast` can accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. This behavior is disabled by default which means values passed to the affected components will always be interpreted as plaintext. Developers can enable this custom HTML behavior by setting `innerHTMLTemplatesEnabled: true` in the [IonicConfig](../developing/config#ionicconfig).

`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-select-option`, and `ion-toast` can accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. This behavior is disabled by default which means values passed to the affected components will always be interpreted as plaintext. Developers can enable this custom HTML behavior by setting `innerHTMLTemplatesEnabled: true` in the [IonicConfig](../developing/config.md#ionicconfig).

thetaPC · 2026-05-22T14:06:06Z

+   * example: `{ innerHTMLTemplatesEnabled: true }`. Merges with the active
+   * preview `mode` when opening the editor.
+   */
+  ionicConfig?: IonicConfig;


I don't mind this, but my concern is that it might be confusing for devs who are reviewing the demos. Some might not realize the important admonition and only copy/paste code. They'll probably think that the select option has a bug. If we included innerHTMLTemplatesEnabled within the code then we can avoid this.

I don't feel strongly about this since:

you do have that admonition

the demos only provide the bare minimal (meaning we don't show files like App.tsx to showcase config changes)

thetaPC · 2026-05-22T17:07:41Z

+
+## Ionic Config
+
+Pass an [IonicConfig](/docs/developing/config#ionicconfig) object so generated StackBlitz projects bootstrap with the same settings. This is merged with the active preview `mode` when opening the editor. Only string, number, and boolean values are injected into generated code:


By adding .md, it will be easier to migrate the files later from .md to .mdx.

Suggested change

Pass an [IonicConfig](/docs/developing/config#ionicconfig) object so generated StackBlitz projects bootstrap with the same settings. This is merged with the active preview `mode` when opening the editor. Only string, number, and boolean values are injected into generated code:

Pass an [IonicConfig](/docs/developing/config.md#ionicconfig) object so generated StackBlitz projects bootstrap with the same settings. This is merged with the active preview `mode` when opening the editor. Only string, number, and boolean values are injected into generated code:

brandyscarney added 4 commits May 19, 2026 16:23

chore(): use dev build

f4ea004

docs(guide): add ion-select-option to guides mentioning innerHTML

ec02fee

feat(stackblitz): add support for passing IonicConfig to StackBlitz

004228d

docs(select): add rich content options playground

6f73533

vercel Bot deployed to Preview May 20, 2026 15:56 View deployment

style: add comment on dev build

ca1f07f

brandyscarney commented May 20, 2026

View reviewed changes

docs(select): add section description to Rich Content Options

3396381

vercel Bot deployed to Preview May 20, 2026 18:19 View deployment

brandyscarney marked this pull request as ready for review May 20, 2026 18:26

brandyscarney requested a review from a team as a code owner May 20, 2026 18:26

brandyscarney requested review from gnbm and thetaPC and removed request for a team and gnbm May 20, 2026 18:26

Merge branch 'major-9.0' into FW-7289

c3e75e5

vercel Bot deployed to Preview May 20, 2026 19:34 View deployment

thetaPC approved these changes May 22, 2026

View reviewed changes

chore(): use latest dev build

6848c26

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


		## Ionic Config

		Pass an [IonicConfig](/docs/developing/config#ionicconfig) object so generated StackBlitz projects bootstrap with the same settings. This is merged with the active preview `mode` when opening the editor. Only string, number, and boolean values are injected into generated code:

	Rich content in select options is disabled by default. Set [`innerHTMLTemplatesEnabled`](/docs/developing/config#ionicconfig) to `true` in your [global Ionic config](/docs/developing/config#global-config). Markup inside options is treated as plain text when it is disabled. Refer to [Security](/docs/techniques/security.md) for sanitization guidance when enabling custom HTML.
	Rich content in select options is disabled by default. Set [`innerHTMLTemplatesEnabled`](/docs/developing/config.md#ionicconfig) to `true` in your [global Ionic config](/docs/developing/config.md#global-config). Markup inside options is treated as plain text when it is disabled. Refer to [Security](/docs/techniques/security.md) for sanitization guidance when enabling custom HTML.

Conversation

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

Uh oh!

Uh oh!

vercel Bot commented May 20, 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!

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

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brandyscarney commented May 20, 2026 •

edited

Loading

vercel Bot commented May 20, 2026 •

edited

Loading