feat(input-otp): add hint text and input label formatter by ShaneK · Pull Request #31661 · ionic-team/ionic-framework

ShaneK · 2026-10-27T20:46:17Z

Issue number: resolves #31619

What is the current behavior?

Currently, the boxes are always named "Input 1 of 4" in English, and host ARIA attributes go on the role="group" wrapper instead of the inputs. There's no helper or error text, and --border-color can't override the fill defaults, so the border contrast can't be fixed without changing --ion-color-step-300.

What is the new behavior?

Added inputLabelFormatter(index, length) for translated box names. A host aria-label or aria-labelledby also names the boxes ("PIN, 1 of 4").
Host aria-describedby, aria-invalid, aria-errormessage and aria-required now go on the inputs.
Added helperText and errorText, matching ion-input.
--border-color overrides every fill and state, and isn't inherited from ancestors like ion-modal.

Does this introduce a breaking change?

Yes
No

Other information

Focus is still shown by the border color, but it can be overwritten with a variable now. Apps can set the unfocused border with --border-color and the focused one with --highlight-color-focused to reach 3:1.

Overriding --border-color needs a class selector (e.g., ion-input-otp.custom). Docs: ionic-team/ionic-docs#4809

a11y test page (iOS)
a11y test page (MD)

vercel · 2026-10-27T20:46:23Z

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

Project	Deployment	Actions	Updated
ionic-framework	Ready	Preview	Oct 28, 2026 2:16pm UTC

brandyscarney

Looks good, added some non-blocking requests!

brandyscarney · 2026-10-29T22:12:30Z

+ * clear them. They stay on the host instead, which only works for global
+ * attributes since the host has no role.
+ */
+const HOST_ARIA_ATTRIBUTES = ['aria-describedby', 'aria-invalid'];


aria-errormessage and aria-required have the same problem this comment describes: an app can't remove them once they're in the initial markup. Should they be in this list too?

brandyscarney · 2026-10-29T23:03:23Z

+      <h2>Host aria-describedby and aria-invalid</h2>
+      <ion-input-otp id="host-aria" length="4" aria-label="Code"></ion-input-otp>
+      <p id="server-error">The server rejected this code</p>
+      <button id="toggle-host-aria">Toggle host error</button>


This only changes ARIA, so clicking it doesn't change anything on screen, and the error message is visible the whole time. Could the button show and hide #server-error along with the attributes, or show the current aria-invalid value next to it? That way it's clear the toggle did something.

brandyscarney · 2026-10-29T23:05:52Z

+   * With a host `aria-labelledby`, each box also references itself so its
+   * position is still read.
+   */
+  private getInputLabelAttributes(index: number, hostAttributes: Attributes) {


A host aria-label produces "PIN, 1 of 4", but a host aria-labelledby produces "Verification code 1 of 4", because the browser joins the references with a space. Should these match? Dropping the comma would make them match, and the aria-labelledby path can't easily add one.

brandyscarney · 2026-10-29T23:07:45Z

+      await expect(page.locator('ion-input-otp .input-otp-group')).toHaveAttribute('aria-label', 'Code');
+    });
+
+    test('should describe the group, not each input, with the slotted description', async ({ page }, testInfo) => {


This is the same check as "should describe the group, not each input, with the slotted description" in input-otp.spec.ts:110. Is the e2e version needed for something the spec can't cover? If it's just the toBeVisible(), the spec version could be dropped instead.

If we keep this, it covers behavior added in this PR rather than something reported in #31619, so I'd drop the issue annotation.

Same for the annotations on "should forward aria-invalid and aria-describedby set on the host after load", "should clear aria-invalid and aria-describedby from the inputs when removed from the host", "should rename the inputs when the host aria-label changes", and "should restore the default labels when a host aria-label set after load is removed". #31619 reports attributes in the initial markup; changes after load are new behavior from this PR.

With VoiceOver, typing a digit moves focus to the next box while the digit is still being echoed, so "PIN, 2 of 4" gets cut off by the echo. It happened with "Input 2 of 4" too, but the longer name makes it more noticeable. Dropping the comma would shorten the pause a bit. Not blocking.

brandyscarney · 2026-10-29T23:07:56Z

+        await expect(input).toHaveCSS('border-top-color', 'rgb(255, 0, 0)');
+      });
+
+      test(`${fill} fill should not inherit --border-color from an ancestor`, async ({ page }, testInfo) => {


This covers behavior added in this PR rather than something reported in #31619, so I'd drop the issue annotation.

brandyscarney · 2026-10-29T23:10:20Z

+      await expect(inputOtp).toHaveScreenshot(screenshot(`input-otp-helper-text-wrapping`));
+    });
+
+    test('should not have visual regressions when rendering error text', async ({ page }) => {


The basic page shows error text under a description, but no screenshot covers that combination. Could this one include slotted Description text?

thetaPC

LGTM, left non-blocking comments

thetaPC · 2026-10-30T02:40:54Z

Can we trim the white spacing around the component? I'm not seeing the need to have it.

thetaPC · 2026-10-30T02:47:27Z

+    return this.el.querySelector('.input-otp-description')?.textContent?.trim();
+  }
+
+  private getHintTextId(): string | undefined {


We really should just make this a util. We have a lot of form controls that use this. Could be a follow up.

thetaPC · 2026-10-30T16:12:04Z

+
+        const input = page.locator('ion-input-otp input').first();
+        await expect(input).toHaveCSS('border-top-color', 'rgb(255, 0, 0)');
+      });


:host(.ion-touched.ion-invalid) compiles to three classes, so it beats ion-input-otp.custom-border and the invalid border stays visible over a custom --border-color, which seems right

Only the resting state is tested, so if the invalid border later moves onto --internal-border-color like the fill defaults did, a custom --border-color would hide it and no test would fail

Suggested change

});

});

test(`${fill} fill should keep the invalid border over a --border-color set on the host`, async ({ page }) => {

await page.setContent(

`

<style>

ion-input-otp.custom-border {

--border-color: rgb(255, 0, 0);

--highlight-color-invalid: rgb(0, 0, 255);

}

</style>

<ion-input-otp class="custom-border ion-touched ion-invalid" fill="${fill}"></ion-input-otp>

`,

config

);

const input = page.locator('ion-input-otp input').first();

await expect(input).toHaveCSS('border-top-color', 'rgb(0, 0, 255)');

});

thetaPC · 2026-10-30T16:19:43Z

+      await expect(page.locator('ion-input-otp .input-otp-group')).toHaveAttribute('aria-label', 'Code');
+    });
+
+    test('should describe the group, not each input, with the slotted description', async ({ page }, testInfo) => {


Same for the annotations on "should forward aria-invalid and aria-describedby set on the host after load", "should clear aria-invalid and aria-describedby from the inputs when removed from the host", "should rename the inputs when the host aria-label changes", and "should restore the default labels when a host aria-label set after load is removed". #31619 reports attributes in the initial markup; changes after load are new behavior from this PR.

thetaPC · 2026-10-30T17:57:06Z

+      await expect(page.locator('ion-input-otp .input-otp-group')).toHaveAttribute('aria-label', 'Code');
+    });
+
+    test('should describe the group, not each input, with the slotted description', async ({ page }, testInfo) => {


With VoiceOver, typing a digit moves focus to the next box while the digit is still being echoed, so "PIN, 2 of 4" gets cut off by the echo. It happened with "Input 2 of 4" too, but the longer name makes it more noticeable. Dropping the comma would shorten the pause a bit. Not blocking.

thetaPC · 2026-10-30T18:06:50Z

@ShaneK The PR description says --border-color "overrides every fill and state", but focus, valid, invalid and the color variants keep their own border. Could it say it overrides the default border in every fill, including disabled and readonly?

ShaneK requested a review from a team as a code owner October 27, 2026 20:46

ShaneK requested a review from brandyscarney October 27, 2026 20:46

github-actions Bot added package: core @ionic/core package package: angular @ionic/angular package package: vue @ionic/vue package labels Oct 27, 2026

ShaneK mentioned this pull request Oct 27, 2026

docs(input-otp): document helper and error text, input labels, and fo… ionic-team/ionic-docs#4809

Open

vercel Bot deployed to Preview October 27, 2026 21:14

View deployment

ShaneK force-pushed the FW-7910 branch from 2e09cf8 to 714359c Compare October 27, 2026 21:43

vercel Bot deployed to Preview October 27, 2026 21:47

View deployment

vercel Bot deployed to Preview October 27, 2026 22:00

View deployment

vercel Bot deployed to Preview October 27, 2026 22:25

View deployment

feat(input-otp): add helper and error text and input label formatter

1c6621e

ShaneK force-pushed the FW-7910 branch from 6673417 to 1c6621e Compare October 28, 2026 13:43

ShaneK changed the title ~~feat(input-otp): add hint text, label formatter and focus ring~~ feat(input-otp): add hint text and input label formatter Oct 28, 2026

vercel Bot deployed to Preview October 28, 2026 13:47

View deployment

chore(): add updated snapshots

9a7d413

vercel Bot deployed to Preview October 28, 2026 14:16

View deployment

brandyscarney approved these changes Oct 29, 2026

View reviewed changes

thetaPC approved these changes Oct 30, 2026

View reviewed changes

-      });
+      });
+      test(`${fill} fill should keep the invalid border over a --border-color set on the host`, async ({ page }) => {
+        await page.setContent(
+          `
+          <style>
+            ion-input-otp.custom-border {
+              --border-color: rgb(255, 0, 0);
+              --highlight-color-invalid: rgb(0, 0, 255);
+            }
+          </style>
+          <ion-input-otp class="custom-border ion-touched ion-invalid" fill="${fill}"></ion-input-otp>
+        `,
+          config
+        );
+        const input = page.locator('ion-input-otp input').first();
+        await expect(input).toHaveCSS('border-top-color', 'rgb(0, 0, 255)');
+      });

Conversation

ShaneK commented Oct 27, 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 Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

thetaPC commented Oct 30, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ShaneK commented Oct 27, 2026 •

edited

Loading

vercel Bot commented Oct 27, 2026 •

edited

Loading