Input phone

When to use

Use input phone to collect an international phone number where the person filling the form may need to pick a country other than your application's default. For a single, known country with no need for a country selector, a plain input set up for phone numbers is simpler and lighter. See Alternatives below for a side by side comparison.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/input-phone.js";
import "@eunomia/elements/label.js";

<eun-input-phone label="Phone number" country="FR"></eun-input-phone>

document
  .querySelector("eun-input-phone")
  .addEventListener("eunchange", (event) => {
    console.log(event.target.value); // e.g. "+33612345678"
  });

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/input-phone.js";
  import "@eunomia/elements/label.js";
</script>

<eun-input-phone label="Phone number" country="FR"></eun-input-phone>

<script>
  document
    .querySelector("eun-input-phone")
    .addEventListener("eunchange", (event) => {
      console.log(event.target.value);
    });
</script>

npm install @eunomia/elements

import "@eunomia/elements/input-phone.js";
import "@eunomia/elements/label.js";

function PhoneField() {
  return (
    <eun-input-phone
      label="Phone number"
      country="FR"
      oneunchange={(event) => console.log(event.target.value)}
    />
  );
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/input-phone.js";
import "@eunomia/elements/label.js";

export function PhoneField() {
  return (
    <eun-input-phone
      label="Phone number"
      country="FR"
      oneunchange={(event) => console.log(event.target.value)}
    />
  );
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/input-phone.js";
  import "@eunomia/elements/label.js";
</script>

<template>
  <eun-input-phone
    label="Phone number"
    country="FR"
    @eunchange="(event) => console.log(event.target.value)"
  />
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/input-phone.js";
import "@eunomia/elements/label.js";

@Component({
  selector: "app-phone-field",
  template: `
    <eun-input-phone
      label="Phone number"
      country="FR"
      (eunchange)="onChange($event)"
    ></eun-input-phone>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class PhoneFieldComponent {
  onChange(event: Event) {
    console.log((event.target as HTMLElement & { value: string }).value);
  }
}

Alternatives

Guidance

Live testing

Properties

Countries

Every country the dropdown offers by default (i.e. with no restricting <option> children, see "Country dropdown" in the Examples tab), with the flag/name shown in its own row and the +<dial code> prefix plus maximum national number length (221 total) this component derives from it. Generated straight from input-phone.type.ts's own table, so it always matches what actually ships.

Variants

Set variant to switch between the bordered box (outline, default), a filled background with no border (fill), and a bottom-only border (underline).

<eun-input-phone
  variant="fill"
  label="Phone number"
  country="FR"
></eun-input-phone>
<eun-input-phone
  variant="underline"
  label="Phone number"
  country="FR"
></eun-input-phone>

Part of the shared vocabulary covered in Variants, alongside every other component that reuses it.

Value format

The value emitted through eunchange (and used for form submission) is an E.164 string, e.g. +33612345678: the country's dial code followed by the raw digits, with no spaces. The visible field only ever shows the grouped national digits.

<eun-input-phone
  label="Phone number"
  country="FR"
  value="+33612345678"
></eun-input-phone>

Domestic format (leading 0)

Most numbering plans in this table write their numbers with a leading trunk 0 domestically (e.g. a French mobile is dialed 06 12 34 56 78 at home, but +33 6 12 34 56 78 abroad). Type it that way and the leading 0 stays visible in the field exactly as typed: it's only excluded from value (E.164 has no place for it) and from the country's own digit cap, so it never displaces a real digit off the end to make room for a 0 that was never part of the significant number to begin with. The default placeholder reflects the same convention, shown as (0) ahead of the digits, the parentheses being the common way to signal "domestic-only, drop it internationally".

<eun-input-phone label="Phone number" country="FR"></eun-input-phone>

Typed:     0612345678    (10 digits, domestic format)
Displayed: 06 12 34 56 78 (leading 0 kept)
value:     +33612345678  (leading 0 excluded)

Per-country digit limit

Typing stops accepting new digits once the selected country's own maximum national number length is reached: 9 for France below, so an 11-digit paste only keeps the first 9. Switching country re-trims whatever's already typed to the newly-selected country's own limit, in case it's shorter (try pasting the number below, then switching to Andorra in the dropdown).

<eun-input-phone label="Phone number" country="FR"></eun-input-phone>

Typed: 61234567890 (11 digits)
Kept:  612345678   (9 digits, France's own maximum)

No country selected

country has no forced default: until one is set (by you, default-country, or through the dropdown), the field still accepts typed digits, but value stays empty since there's no dial code to build an E.164 string with. The country-selector button shows a generic globe glyph (🌐) instead of a blank flag while unset.

<eun-input-phone label="Phone number"></eun-input-phone>

Placeholder

When placeholder isn't set explicitly, the field falls back to a formatted generic digit pattern prefixed with (0), the conventional parenthesized trunk prefix that hints a leading 0 is welcome and domestic-only. It always shows the grouping style typed digits will get, though this is not a real per-country example number (no phone-number library is used, so there's no per-country length data to draw one from). Set placeholder explicitly to override it.

<eun-input-phone
  label="Phone number"
  country="FR"
  placeholder="Your phone number"
></eun-input-phone>

Hiding the dial code indicator

Set hide-dial-code to omit the +<dial code> prefix inside the phone field. It's useful in tight layouts, or when the dial code is shown elsewhere.

<eun-input-phone
  hide-dial-code
  label="Phone number"
  country="FR"
></eun-input-phone>

Hiding the country selector

Set hide-country-selector to remove the leading flag/dropdown part entirely, leaving only the phone field. country can still be set programmatically (e.g. a fixed-country form): there's simply no picker UI to change it.

<eun-input-phone
  hide-country-selector
  label="Phone number"
  country="FR"
></eun-input-phone>

Country dropdown

The leading button opens a searchable list of countries (flag, name, dial code), filtered as you type in its own search field. Like eun-select's own dropdown, it's a popover="auto" element: rendered in the browser's top layer and dismissed automatically on outside click or Escape.

By default, every built-in country is available. Pass <option value="ISO">Name</option> elements as children to restrict the dropdown to a specific set, the same convention eun-select uses for its own choices. default-country sets the initial selection when country isn't provided explicitly.

<eun-input-phone label="Phone number" default-country="FR">
  <option value="FR">France</option>
  <option value="BE">Belgium</option>
  <option value="CH">Switzerland</option>
  <option value="CA">Canada</option>
  <option value="US">United States</option>
  <option value="GB">United Kingdom</option>
  <option value="DE">Germany</option>
</eun-input-phone>

States

Disabled

<eun-input-phone
  disabled
  label="Phone number"
  country="FR"
  value="+33612345678"
></eun-input-phone>

Readonly

<eun-input-phone
  readonly
  label="Phone number"
  country="FR"
  value="+33612345678"
></eun-input-phone>

Required

<eun-input-phone required label="Phone number" country="FR"></eun-input-phone>

Hint and validation

Same hint/validators/hide-error mechanics as every other field built on FormMixin. See Forms & validation for the full pattern.

<eun-input-phone
  label="Phone number"
  country="FR"
  hint="We'll only text you a verification code."
></eun-input-phone>

Keyboard interactions

Dismissal behavior

The dropdown closes on: Escape, a click outside it (both native Popover API light-dismiss), picking a country, the browser window itself losing focus (e.g. Alt-Tabbing to another application, not something the Popover API handles on its own, since light-dismiss only reacts to clicks and Escape), and focus leaving the trigger/dropdown entirely (e.g. Tab-ing past the search field, since light-dismiss doesn't cover keyboard-only focus changes either). It also closes if the field itself scrolls behind a reserved --eun-viewport-inset-top/-bottom band while open. See "Dropdown positioning" below, and eun-select's own Accessibility tab, which documents the identical mechanism in more depth.

Aria attributes

• The country-selector button carries aria-haspopup="listbox", aria-expanded (reflecting whether the dropdown is open), aria-controls="listbox", and a configurable aria-label (ariaLabelCountrySelector, "Select a country" by default): its visible content (a flag only) isn't a sufficient accessible name on its own
• The dropdown panel itself carries role="listbox" with a matching aria-label, and each country row carries role="option" / aria-selected="true"\|"false"
• The phone field carries aria-invalid="true"\|"false", kept in sync with the field's validity, and aria-describedby="description" whenever a hint or error message is actually rendered below it
• The phone field is associated with its eun-label through the for/id relationship, exactly like eun-input. Refer to its Accessibility tab for mandatory-field indication and message management, which apply identically here

Dropdown positioning

The dropdown panel's position tracks the whole field (both the country-selector button and the phone field together) on every scroll and resize, flipping above it instead of below whenever there isn't enough room underneath. This uses the exact same AnchorPositionMixin as eun-select: CSS Anchor Positioning natively where supported, a JS fallback everywhere else, so --eun-viewport-inset-top/--eun-viewport-inset-bottom (reserved space for page chrome like a sticky header) and --field-listbox-max-height both apply here identically. See eun-select's own Accessibility tab ("Dropdown panel: rendering, positioning, and sizing") for the full explanation.

Disabled vs. readonly

disabled removes both the country-selector button and the phone field from the tab order, and excludes the value from form submission entirely. readonly keeps the phone field focusable and its value submitted, but prevents typing into it and disables the country-selector button, since there's nothing to change. This communicates "you can't change this right now", not "this doesn't apply".

Label accessibility

Always set label (or slot content into eun-label's label slot): a phone field with no accessible name is as disruptive for screen-reader users as any other unlabeled text field. The country-selector button's own aria-label (ariaLabelCountrySelector) is separate from this and always present, since a flag glyph alone never makes an adequate accessible name.

Reference links

WAI-ARIA Authoring Practices: Combobox Pattern
WAI-ARIA Authoring Practices: Listbox Pattern
WAI Web Accessibility Tutorials: Labeling Controls
WHATWG HTML: Popover API
CSS Anchor Positioning: Working Draft