feat(select): allow HTML within options by thetaPC · Pull Request #31072 · ionic-team/ionic-framework

thetaPC · 2026-04-09T16:35:40Z

Issue number: resolves #29890

What is the current behavior?

Select only allows plain text to be passed within it's options.

What is the new behavior?

ion-select-option

Added default slot support for custom HTML content (images, avatars, icons, etc.) when innerHTMLTemplatesEnabled is true
Added start and end named slots for content that appears in the overlay interface but not in the selected text
Added description prop for text rendered below the option label in the overlay

ion-select

Selected text renders HTML content from the default slot, excluding start/end slot content
aria-label derives plain text only from the default slot, ensuring screen readers don't read slotted or element content
Added CSS variables for styling media within the selected text (--select-text-media-width, --select-text-media-height, etc.)

Overlay interfaces (alert, action-sheet, select-popover, select-modal)

All four interfaces render rich content (start, end, description, HTML label) consistently via the shared renderOptionLabel utility
Public interfaces (ActionSheetButton, AlertInput, SelectPopoverOption, SelectModalOption) are unchanged — rich content fields are on internal extended interfaces (SelectActionSheetButton, SelectAlertInput, SelectOverlayOption)
Content is sanitized via sanitizeDOMString before DOM injection to prevent XSS

Utilities

Added select-option-render.tsx: shared render utility for option labels across all overlay components
Added getOptionContent: extracts and clones slot content from ion-select-option for overlays and selected text
Added getDefaultSlotPlainText — extracts plain text from the default slot, used for labels and aria

Tests

Added E2E tests for rich content rendering across all four interfaces (single and multiple selection)
Added tests for slot positioning (start/end placement verification)
Added tests for selected text content verification (excludes slotted content)

Does this introduce a breaking change?

Yes
No

No, developers will be able to continue using plain text for select options as usual.

Other information

Preview

vercel · 2026-04-09T16:36:22Z

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

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	Apr 25, 2026 3:32am

…7137

thetaPC · 2026-04-10T18:16:06Z

+// --------------------------------------------------
+
+.action-sheet-button-label {
+  gap: 12px;


I decided to use the same value that ionic uses.

thetaPC · 2026-04-10T18:17:21Z

-            <div class="alert-button-inner">
-              <div class="alert-checkbox-icon">
-                <div class="alert-checkbox-inner"></div>
+        {inputs.map((i) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:17:24Z

-            <div class="alert-button-inner">
-              <div class="alert-radio-icon">
-                <div class="alert-radio-inner"></div>
+        {inputs.map((i) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:17:38Z

-                   */
-                  this.closeModal();
-                }
+        {this.options.map((option, index) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:17:46Z

-          onIonChange={(ev) => {
-            this.setChecked(ev);
-            this.callOptionHandler(ev);
+    return this.options.map((option, index) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:19:05Z

+  /**
+   * Text that is placed underneath the option text to provide additional details about the option.
+   */
+  @Prop() description?: string;


Description isn't being used here to display on the screen because ion-select-option isn't used to display the options, it's done through the respective interface. So description is passed to the interface.

thetaPC · 2026-04-10T18:20:34Z

+        <slot name="start"></slot>
+        <slot></slot>
+        <slot name="end"></slot>


Slots aren't being used here to display on the screen because ion-select-option isn't used to display the options, it's done through the respective interface. So slots are passed to the interface and the rendering is done with a new utility.

Even though it's not used to display here, it's still useful to include here so the docs can generate that "slots" are available for the options.

Adding the slots here isn't what generates the docs. You need to add this to the component:

ionic-framework/core/src/components/item/item.tsx

Lines 16 to 18 in 0db5b40

* @slot - Content is placed between the named slots if provided without a slot.

* @slot start - Content is placed to the left of the item text in LTR, and to the right in RTL.

* @slot end - Content is placed to the right of the item text in LTR, and to the left in RTL.

thetaPC · 2026-04-10T18:21:40Z

-          onIonChange={(ev) => {
-            this.setChecked(ev);
-            this.callOptionHandler(ev);
+    return options.map((option, index) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-10T18:21:47Z

-                   */
-                  this.dismissParentPopover();
-                }
+        {options.map((option, index) => {


The only change is the addition of optionLabelOptions and renderOptionLabel

thetaPC · 2026-04-15T23:26:04Z

+// --------------------------------------------------
+
+.action-sheet-button-label {
+  gap: 12px;


Based it off ionic theme

ShaneK

Looks good to me! I consider these comments to be optional side quests (nits), feel free to disregard

ShaneK · 2026-04-20T18:23:08Z

+
+import { sanitizeDOMString } from './sanitization';
+
+interface RichContentOption {


RichContentOption is declared here with id, label, startContent, endContent, description, and a separate RichContentOption in select-interface.ts has only the three content fields. Same name, different shape, no shared source. Could we export one from select-interface.ts and import it here so we can avoid drift?

ShaneK · 2026-04-20T18:27:40Z

+            <ion-select id="alert-select" label="Alert" placeholder="Select one" interface="alert">
+              <ion-select-option value="full" description="Choose me!">
+                <ion-badge slot="end">NEW</ion-badge>
+                <ion-avatar id="avatar" slot="start" size="large">


id="avatar" is repeated 35+ times on this page (lines 60, 67, 74, etc.) Duplicate IDs are invalid HTML and none of the tests query by this id. Can we drop the attribute? I assume it's just copy pasta at this point

ShaneK · 2026-04-20T18:27:52Z

+
+  // Render simple string label if there is no rich content to display
+  if (!hasRichContent && (typeof label === 'string' || !label)) {
+    // const Tag = useSpan ? 'span' : 'div';


Dead commented line, Tag is already declared at line 84. Can you drop this?

…7137

brandyscarney · 2026-04-24T18:11:25Z

The popover example has cut off elements inside of it in all themes:

ionic ios md

brandyscarney · 2026-04-24T18:41:00Z

In the ionic theme, when you open and close the modal from the icon it scrolls to the bottom of the view and also the focus indicator is cut off:

bug-with-select-multiple.mov

This does not happen for:

The single value modal example

The ios theme

The md theme

The overflowing or multiple basic select test on next

However, the focus indicator issue is there on the multiple example

Note: I didn't test if this exact test has the issue on next since this test is new.

I was not able to replicate either issues on Chrome and Firefox. What are the steps you took?

brandyscarney · 2026-04-24T18:52:55Z

Can we add screenshot tests for this? We need to check the visual rendering as well.

The reason that I didn't create screenshots for this is because the content for the options are based on the project so they're not fixed. Would it be beneficial to create screenshots for something like that?

brandyscarney · 2026-04-24T19:08:37Z

The checkbox for the multiple value select modal looks different than the UX requirements - do we have a way for them to make this change?

Our implementation Figma requirements

That isn't part of the scope in my opinion. The ticket is meant to add HTML content to the options.

brandyscarney · 2026-04-24T19:12:46Z

+        <slot name="start"></slot>
+        <slot></slot>
+        <slot name="end"></slot>


Adding the slots here isn't what generates the docs. You need to add this to the component:

ionic-framework/core/src/components/item/item.tsx

Lines 16 to 18 in 0db5b40

* @slot - Content is placed between the named slots if provided without a slot.

* @slot start - Content is placed to the left of the item text in LTR, and to the right in RTL.

* @slot end - Content is placed to the right of the item text in LTR, and to the left in RTL.

brandyscarney · 2026-04-24T19:55:26Z

+  return container;
+};
+
+const getOptionDefaultSlot = (option: HTMLIonSelectOptionElement): Node[] | null => {


Can we add a comment describing this function since the others have comments?

brandyscarney · 2026-04-24T19:57:13Z

+
+import { sanitizeDOMString } from './sanitization';
+
+interface RichContentOption extends RichContentOpt {


Why did we redefine this here instead of adding those properties to select-interface?

I wanted the types to be strict.

brandyscarney · 2026-04-24T20:21:33Z

+ * @param useSpan - Whether to use a span element instead of a div for the wrapper.
+ */
+const renderClonedContent = (id: string, content: HTMLElement, className: string, useSpan = false) => {
+  const Tag = useSpan ? 'span' : 'div';


I understand why the span is required, but why do we ever need to render as a div?

It's based on the flow of the interface. When it comes to action sheet, that is using buttons to render the option so we should be using span. The other interfaces are using divs to render the option. So in order to be consistent with the flow, I have it using a div.

brandyscarney · 2026-04-24T20:22:22Z

+): HTMLElement | string | undefined => {
+  const { id, label, startContent, endContent, description } = option;
+  const hasRichContent = !!startContent || !!endContent || !!description;
+  const Tag = useSpan ? 'span' : 'div';


I understand why the span is required, but why do we ever need to render as a div?

#31072 (comment)

brandyscarney · 2026-04-24T20:27:40Z

The avatar size in md theme is way too large. Can we decrease it here to match the other themes?

I would prefer to not modify the width since we'll eventually add sizes to native avatar and we can adjust it at that point. Let me know if you would still prefer to make the change now.

feat(select): allow HTML within options

9918f4a

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

feat(select): add HTML to options

d0a8a56

github-actions Bot added package: angular @ionic/angular package package: vue @ionic/vue package labels Apr 10, 2026

vercel Bot deployed to Preview April 10, 2026 03:46 View deployment

refactor(many): rename files to common

d53d627

vercel Bot deployed to Preview April 10, 2026 03:48 View deployment

chore(select): run build

5415cad

vercel Bot deployed to Preview April 10, 2026 03:52 View deployment

thetaPC added 2 commits April 9, 2026 21:11

refactor(select): cleanup

8f3e623

Merge branch 'next' of github.com:ionic-team/ionic-framework into FW-…

f0b45d3

…7137

vercel Bot deployed to Preview April 10, 2026 04:14 View deployment

chore(): run build proper

a48cf66

vercel Bot deployed to Preview April 10, 2026 04:19 View deployment

thetaPC commented Apr 10, 2026

View reviewed changes

refactor(select): cleanup and tests

e9eb575

vercel Bot deployed to Preview April 10, 2026 22:59 View deployment

refactor(select): select text spacing

e4bce6b

vercel Bot deployed to Preview April 10, 2026 23:35 View deployment

fix(select): revert deletion

03b8351

vercel Bot deployed to Preview April 14, 2026 18:34 View deployment

fix(select): sanitize content

22dace3

vercel Bot deployed to Preview April 14, 2026 21:23 View deployment

feat(select): add spans to rich content select text

f2695ca

vercel Bot deployed to Preview April 15, 2026 13:56 View deployment

test(select): add rich content page

8a4e59b

vercel Bot deployed to Preview April 15, 2026 20:14 View deployment

feat(select): strip out elements for plain options

deaafb9

vercel Bot deployed to Preview April 15, 2026 23:20 View deployment

thetaPC commented Apr 15, 2026

View reviewed changes

thetaPC requested a review from ShaneK April 16, 2026 01:06

mfernando797-gif approved these changes Apr 19, 2026

View reviewed changes

ShaneK approved these changes Apr 20, 2026

View reviewed changes

thetaPC added 2 commits April 22, 2026 10:43

refactor(select-option): remove comment

96a4bb3

test(select-option): remove ids

7fad490

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

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

refactor(select): export RichContentOption

d6332e7

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

Merge branch 'next' of github.com:ionic-team/ionic-framework into FW-…

cd276fc

…7137

vercel Bot deployed to Preview April 22, 2026 18:47 View deployment

brandyscarney requested changes Apr 24, 2026

View reviewed changes

fix(select-popover): add max content width

968103a

vercel Bot deployed to Preview April 24, 2026 23:50 View deployment

fix(select-popover): adjust the width to the option content

8009bfe

vercel Bot deployed to Preview April 25, 2026 03:08 View deployment

fix(select-option): use correct slot props

91091c2

vercel Bot deployed to Preview April 25, 2026 03:20 View deployment

docs(select): add JSDocs to function

bfd3c52

vercel Bot deployed to Preview April 25, 2026 03:32 View deployment

	* @slot - Content is placed between the named slots if provided without a slot.
	* @slot start - Content is placed to the left of the item text in LTR, and to the right in RTL.
	* @slot end - Content is placed to the right of the item text in LTR, and to the left in RTL.


		import { sanitizeDOMString } from './sanitization';

		interface RichContentOption {


		import { sanitizeDOMString } from './sanitization';

		interface RichContentOption extends RichContentOpt {

Conversation

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

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!

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!

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

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!

thetaPC commented Apr 9, 2026 •

edited

Loading

vercel Bot commented Apr 9, 2026 •

edited

Loading

thetaPC Apr 10, 2026 •

edited

Loading

thetaPC Apr 24, 2026 •

edited

Loading