vue-a11y-phone

vue-a11y-phone

Accessible international phone input for Vue 3. WCAG 2.2 AA, keyboard-first, screen-reader friendly.

• 9 KB JS + 1 KB CSS gzipped
• Zero runtime dependencies
• Vue 3.4+, peer-only

Install

npm install vue-a11y-phone

Usage

<template>
    <Vue3PhoneInput v-model="phone" default-country="se" :preferred-countries="['se', 'no', 'dk']" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { Vue3PhoneInput } from 'vue-a11y-phone';
import 'vue-a11y-phone/vue-a11y-phone.css';

const phone = ref('');
</script>

Global registration

import { createApp } from 'vue';
import VueA11yPhone from 'vue-a11y-phone';
import 'vue-a11y-phone/vue-a11y-phone.css';

const app = createApp(App);
app.use(VueA11yPhone);

Then use <vue3-phone-input> in any template.

Props

Events

Exposed methods

const phoneRef = ref<InstanceType<typeof Vue3PhoneInput>>();

phoneRef.value?.focus();
phoneRef.value?.blur();
phoneRef.value?.validate(); // boolean — current validity

Helpers

The package also exports utilities for working with phone numbers outside the component:

import {
    allCountries,
    formatNational,
    formatSwedishPhone,
    getCountryMeta,
    getNativeName,
    isValidNationalNumber
} from 'vue-a11y-phone';

formatNational('se', '701234567');     // → "70 123 45 67"
formatNational('us', '5551234567');    // → "555 123 4567"
isValidNationalNumber('se', '7012345'); // → true (7+ digits)
getCountryMeta('gb');                   // → { minLength, maxLength, groups }
getNativeName('de');                    // → "Deutschland"

Theming

All styles use CSS custom properties. Override any --v3pi-* variable to customize:

.v3pi {
    --v3pi-border-color: #ced4da;
    --v3pi-border-radius: 0.375rem;
    --v3pi-bg: #ffffff;
    --v3pi-font-family: inherit;
    --v3pi-font-size: 1rem;
    --v3pi-padding-y: 0.375rem;
    --v3pi-padding-x: 0.75rem;
    --v3pi-focus-color: #0d6efd;
    --v3pi-focus-width: 0.25rem;
    --v3pi-error-color: #dc3545;
    --v3pi-hover-shadow: 0 0 0 1px rgba(0, 0, 0, 0.1);
    --v3pi-dropdown-shadow: 0 0.125rem 0.5rem rgba(0, 0, 0, 0.15);
    --v3pi-item-hover-bg: #f8f9fa;
    --v3pi-item-selected-bg: #e9ecef;
    --v3pi-divider-color: #dee2e6;
    --v3pi-disabled-bg: #e9ecef;
    --v3pi-disabled-opacity: 0.65;
}

Accessibility

This component is built for WCAG 2.2 AA compliance:

• Native <input type="tel"> — no fake inputs or masking
• Real <button> for the country selector with aria-expanded, aria-haspopup, and aria-controls
• WAI-ARIA combobox pattern for country search (role="combobox", aria-autocomplete, aria-activedescendant)
• role="listbox" and role="option" with aria-selected for country list
• aria-live="polite" region announcing search result count to screen readers
• aria-label on the phone input, country button, and search input
• aria-describedby linking the phone input to a country hint for screen readers
• aria-invalid support for validation states
• Full keyboard navigation: Arrow keys, Enter, Escape, Tab
• :focus-visible outlines on all interactive elements
• Unique IDs per instance — safe to use multiple components on one page

Keyboard navigation

DOM focus stays on the search input while the dropdown is open; only aria-activedescendant moves through the options. This follows the WAI-ARIA APG combobox pattern.

TypeScript

Full type definitions are included. Import types directly:

import type { Country, CountryMeta, Vue3PhoneInputProps, Vue3PhoneInputEmits } from 'vue-a11y-phone';

Browser support

The component targets evergreen browsers (Chrome, Firefox, Safari, Edge). It uses Intl.DisplayNames for native country names — older browsers fall back to the English name.

Contributing

Issues and pull requests welcome. See CONTRIBUTING.md.

License

MIT © Rickard Lindbom