Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Application-owned text

Most distributed primitives contain no default human-language copy. Labels, option labels, placeholders, slot content, visible control messages, and screen-reader announcements come from the application. MultiSelect requires typed messages for its default chip controls and selection announcement. Select accepts optional messages; when its compatibility clearable control can render, supply messages.clearSelection or clearLabel. Their placeholders are optional and have no fallback.

DataTable follows the established data-grid localeText pattern: it works with editable English defaults and accepts an optional partial object for overrides or translations. Missing entries keep their English defaults. Pass a computed object from your i18n library when the language can change at runtime; function entries own grammar and pluralization.

vue
<DataTable
  :data="orders"
  :columns="columns"
  :locale-text="{
    search: 'Rechercher',
    noResults: 'Aucune commande trouvée',
    next: 'Page suivante',
  }"
/>
ts
import { computed } from 'vue'

const tableText = computed(() => ({
  search: t('table.search'),
  noResults: t('table.noResults'),
  selected: (count: number) => t('table.selected', { count }),
}))

TagsInput and DateTimePicker use the same low-setup pattern for their small amount of built-in control text. Ordinary English usage needs no message object. Override one entry directly, or pass a computed partial object from an i18n library; all omitted entries keep their English defaults.

vue
<TagsInput
  v-model="skills"
  :locale-text="{ removeTag: value => t('tags.remove', { value }) }"
/>

<DateTimePicker
  v-model="startsAt"
  :locale-text="{
    dateLabel: t('date.label'),
    timeLabel: t('time.label'),
    date: { nextMonth: t('date.nextMonth') },
  }"
/>

NumberInput likewise requires messages: { increment, decrement } for its plus/minus button names. Supply context-specific translations such as your application's “Increase weight” message. Prefix/suffix slots on Input, NumberInput, Button, Select, and MultiSelect are application-owned, so units, text, and icons can update with your locale. NumberInput uses native browser numeric parsing, without imposing a currency or locale formatter.

DatePicker, DatePickerRange, and TimePicker require complete message objects for their visible controls and accessible names. Stepper accepts an application-supplied optionalLabel when optional steps need a visible marker. Date and time triggers show stable YYYY-MM-DD and HH:mm/HH:mm:ss values when locale is omitted; pass an explicit locale for localized display. This keeps server and browser output consistent without inserting English fallback copy.

Use ordinary strings, computed values, or any existing translation library. The components neither import an i18n package nor maintain a locale singleton. Passing computed messages makes locale changes reactive and keeps SSR locale selection in your application.

ts
import { computed } from 'vue'
import type { ListboxMessages, MultiSelectMessages } from './components'

// `t(key, parameters?)` and `locale` come from your application's i18n setup.
const selectMessages = computed<ListboxMessages>(() => ({
  listboxLabel: t('countries.optionsLabel'),
  empty: t('select.empty'),
  clearSelection: t('select.clear'),
}))

const multiMessages = computed<MultiSelectMessages>(() => ({
  listboxLabel: t('countries.optionsLabel'),
  empty: t('select.empty'),
  clear: t('multi.clear'),
  clearSelection: t('multi.clearAccessibleName'),
  changeSelection: t('multi.change'),
  removeSelection: (label) => t('multi.remove', { label }),
  overflow: (count) => t('multi.overflow', { count }),
  selectionSummary: (labels, required) =>
    t(required ? 'multi.requiredSummary' : 'multi.summary', {
      count: labels.length,
      labels: new Intl.ListFormat(locale.value).format(labels),
    }),
}))
vue
<label id="countries-label" for="countries">{{ t('countries.label') }}</label>
<MultiSelect
  id="countries"
  aria-labelledby="countries-label"
  v-model="countries"
  :options="translatedCountryOptions"
  :messages="multiMessages"
  :placeholder="t('countries.placeholder')"
  clearable
  required
/>

Your translation system owns pluralization, grammatical order, punctuation, required-state wording, and overflow number formatting. selectionSummary receives all selected labels, including selections hidden by maxVisibleChips. Return a meaningful sentence for zero, one, and many selections. removeSelection receives the option label. Return nonempty names for all interactive controls; an empty empty message is allowed if you intentionally want no empty-state copy.

The popup reuses aria-labelledby/aria-label from the caller or uses messages.listboxLabel. There is no generic English “Options” fallback. The explicit popup message also works when the trigger is named with a native <label for>; referencing a combobox as another widget's label can resolve its selected value instead of its name. Supply visible trigger labels, and translate error/help text referenced by aria-describedby. Native browser validation messages follow the browser's locale; application-specific errors remain application-owned. Decorative SVGs and check/close symbols are language-neutral.

Migration

Add :messages="multiMessages" to every MultiSelect, and supply any desired placeholder explicitly. Add :messages="selectMessages" to Select when using its compatibility empty state or clear control; a compound Select without those features can omit it. The test catalog is in tests/messages.ts as an application example; it is excluded from registry artifacts. Button, Input, Checkbox, RadioGroup, and Card accept their copy through slots and native attributes.

Tests cover translated strings, dynamic removal labels, custom overflow text, full selection/required announcements, absence of fallback copy, and changing messages while a popup is open.

Textarea and Switch use caller-owned native labels and attributes. Label’s optional required slot adds no built-in wording. Badge and Tooltip content comes from slots; PopoverContent, DropdownMenuContent, and TabsList require caller-owned accessible labels. ToastProvider requires messages: { dismiss, viewportLabel }, while each toast supplies its own title, description, and action label. Menu actions, tab labels, and notification copy can all be translated reactively. Example English copy stays outside the distributed registry.