maz-ui 5.0.0 → 5.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/dist/assets/{MazDropzone.DJ8au25t.css → MazDropzone.BW2grpTi.css} +1 -1
  2. package/dist/chunks/{MazDrawer.DANxKYxJ.js → MazDrawer.CC8zomfx.js} +2 -2
  3. package/dist/chunks/{MazDropzone.POH3pmfi.js → MazDropzone.Dez5j0WP.js} +2 -2
  4. package/dist/components/MazDrawer.js +1 -1
  5. package/dist/components/MazDropzone.js +1 -1
  6. package/dist/components/MazDropzone.vue.d.ts +2 -2
  7. package/dist/components/MazInputPrice.vue.d.ts +1 -1
  8. package/dist/components/index.js +2 -2
  9. package/docs/README.md +207 -0
  10. package/docs/agents/agents-md.md +52 -0
  11. package/docs/agents/claude-rule.md +52 -0
  12. package/docs/components/maz-accordion.md +76 -0
  13. package/docs/components/maz-alert.md +241 -0
  14. package/docs/components/maz-animated-counter.md +87 -0
  15. package/docs/components/maz-animated-element.md +46 -0
  16. package/docs/components/maz-animated-text.md +53 -0
  17. package/docs/components/maz-avatar.md +193 -0
  18. package/docs/components/maz-backdrop.md +178 -0
  19. package/docs/components/maz-badge.md +167 -0
  20. package/docs/components/maz-bottom-sheet.md +257 -0
  21. package/docs/components/maz-btn-group.md +316 -0
  22. package/docs/components/maz-btn.md +423 -0
  23. package/docs/components/maz-card-spotlight.md +84 -0
  24. package/docs/components/maz-card.md +321 -0
  25. package/docs/components/maz-carousel.md +153 -0
  26. package/docs/components/maz-chart.md +206 -0
  27. package/docs/components/maz-checkbox.md +138 -0
  28. package/docs/components/maz-checklist.md +251 -0
  29. package/docs/components/maz-circular-progress-bar.md +109 -0
  30. package/docs/components/maz-code-highlight.md +155 -0
  31. package/docs/components/maz-container.md +241 -0
  32. package/docs/components/maz-date-picker.md +791 -0
  33. package/docs/components/maz-dialog-confirm.md +215 -0
  34. package/docs/components/maz-dialog.md +143 -0
  35. package/docs/components/maz-drawer.md +106 -0
  36. package/docs/components/maz-dropdown.md +419 -0
  37. package/docs/components/maz-dropzone.md +387 -0
  38. package/docs/components/maz-expand-animation.md +82 -0
  39. package/docs/components/maz-fullscreen-loader.md +58 -0
  40. package/docs/components/maz-gallery.md +79 -0
  41. package/docs/components/maz-icon.md +203 -0
  42. package/docs/components/maz-input-code.md +73 -0
  43. package/docs/components/maz-input-number.md +79 -0
  44. package/docs/components/maz-input-phone-number.md +536 -0
  45. package/docs/components/maz-input-price.md +68 -0
  46. package/docs/components/maz-input-tags.md +112 -0
  47. package/docs/components/maz-input.md +334 -0
  48. package/docs/components/maz-lazy-img.md +113 -0
  49. package/docs/components/maz-link.md +146 -0
  50. package/docs/components/maz-loading-bar.md +38 -0
  51. package/docs/components/maz-markdown-editor.md +320 -0
  52. package/docs/components/maz-pagination.md +82 -0
  53. package/docs/components/maz-popover.md +794 -0
  54. package/docs/components/maz-pull-to-refresh.md +222 -0
  55. package/docs/components/maz-radio-buttons.md +313 -0
  56. package/docs/components/maz-radio.md +119 -0
  57. package/docs/components/maz-read-more.md +209 -0
  58. package/docs/components/maz-reading-progress-bar.md +96 -0
  59. package/docs/components/maz-select-country.md +513 -0
  60. package/docs/components/maz-select.md +318 -0
  61. package/docs/components/maz-sidebar-content.md +25 -0
  62. package/docs/components/maz-sidebar-footer.md +25 -0
  63. package/docs/components/maz-sidebar-group.md +27 -0
  64. package/docs/components/maz-sidebar-header.md +25 -0
  65. package/docs/components/maz-sidebar-menu-button.md +41 -0
  66. package/docs/components/maz-sidebar-menu-item.md +25 -0
  67. package/docs/components/maz-sidebar-menu-sub.md +32 -0
  68. package/docs/components/maz-sidebar-menu.md +25 -0
  69. package/docs/components/maz-sidebar-separator.md +21 -0
  70. package/docs/components/maz-sidebar-trigger.md +25 -0
  71. package/docs/components/maz-sidebar.md +507 -0
  72. package/docs/components/maz-skeleton.md +226 -0
  73. package/docs/components/maz-slider.md +165 -0
  74. package/docs/components/maz-spinner.md +84 -0
  75. package/docs/components/maz-stepper.md +301 -0
  76. package/docs/components/maz-switch.md +86 -0
  77. package/docs/components/maz-table-cell.md +27 -0
  78. package/docs/components/maz-table-row.md +28 -0
  79. package/docs/components/maz-table-title.md +27 -0
  80. package/docs/components/maz-table-virtualizer.md +31 -0
  81. package/docs/components/maz-table.md +426 -0
  82. package/docs/components/maz-tabs-bar.md +43 -0
  83. package/docs/components/maz-tabs-content-item.md +27 -0
  84. package/docs/components/maz-tabs-content.md +27 -0
  85. package/docs/components/maz-tabs.md +308 -0
  86. package/docs/components/maz-textarea.md +255 -0
  87. package/docs/components/maz-ticker.md +427 -0
  88. package/docs/components/maz-timeline.md +304 -0
  89. package/docs/components/maz-ui-provider.md +26 -0
  90. package/docs/components/maz-window-mockup.md +182 -0
  91. package/docs/composables/use-aos.md +41 -0
  92. package/docs/composables/use-breakpoints.md +42 -0
  93. package/docs/composables/use-dialog.md +58 -0
  94. package/docs/composables/use-display-names.md +130 -0
  95. package/docs/composables/use-drag.md +185 -0
  96. package/docs/composables/use-form-validator.md +1123 -0
  97. package/docs/composables/use-idle-timeout.md +172 -0
  98. package/docs/composables/use-pull-to-refresh.md +86 -0
  99. package/docs/composables/use-reading-time.md +132 -0
  100. package/docs/composables/use-string-matching.md +41 -0
  101. package/docs/composables/use-swipe.md +171 -0
  102. package/docs/composables/use-timer.md +104 -0
  103. package/docs/composables/use-toast.md +50 -0
  104. package/docs/composables/use-user-visibility.md +127 -0
  105. package/docs/composables/use-wait.md +50 -0
  106. package/docs/composables/use-window-size.md +25 -0
  107. package/docs/directives/click-outside.md +182 -0
  108. package/docs/directives/fullscreen-img.md +83 -0
  109. package/docs/directives/lazy-img.md +182 -0
  110. package/docs/directives/tooltip.md +298 -0
  111. package/docs/directives/zoom-img.md +100 -0
  112. package/docs/ecosystem/eslint-config.md +289 -0
  113. package/docs/ecosystem/icons/icon-set.md +25 -0
  114. package/docs/ecosystem/icons/index.md +584 -0
  115. package/docs/ecosystem/mcp.md +165 -0
  116. package/docs/ecosystem/node/exec-promise.md +93 -0
  117. package/docs/ecosystem/node/index.md +53 -0
  118. package/docs/ecosystem/node/logger.md +152 -0
  119. package/docs/ecosystem/node/print-banner.md +101 -0
  120. package/docs/ecosystem/node/setup-agents.md +102 -0
  121. package/docs/ecosystem/nuxt.md +551 -0
  122. package/docs/ecosystem/stylelint-config.md +310 -0
  123. package/docs/ecosystem/themes.md +966 -0
  124. package/docs/ecosystem/translations.md +1173 -0
  125. package/docs/ecosystem/utils/camel-case.md +37 -0
  126. package/docs/ecosystem/utils/capitalize.md +37 -0
  127. package/docs/ecosystem/utils/check-availability.md +85 -0
  128. package/docs/ecosystem/utils/cookie.md +86 -0
  129. package/docs/ecosystem/utils/country-code-to-unicode-flag.md +128 -0
  130. package/docs/ecosystem/utils/currency.md +53 -0
  131. package/docs/ecosystem/utils/date.md +53 -0
  132. package/docs/ecosystem/utils/debounce-callback.md +44 -0
  133. package/docs/ecosystem/utils/debounce-id.md +75 -0
  134. package/docs/ecosystem/utils/debounce.md +71 -0
  135. package/docs/ecosystem/utils/fetch-locale-ip.md +39 -0
  136. package/docs/ecosystem/utils/format-json.md +39 -0
  137. package/docs/ecosystem/utils/format-phone-number.md +43 -0
  138. package/docs/ecosystem/utils/get-browser-locale.md +35 -0
  139. package/docs/ecosystem/utils/get-country-flag-url.md +67 -0
  140. package/docs/ecosystem/utils/get-error-message.md +45 -0
  141. package/docs/ecosystem/utils/idle-timeout.md +96 -0
  142. package/docs/ecosystem/utils/index.md +57 -0
  143. package/docs/ecosystem/utils/is-client.md +38 -0
  144. package/docs/ecosystem/utils/is-equal.md +44 -0
  145. package/docs/ecosystem/utils/is-ios.md +43 -0
  146. package/docs/ecosystem/utils/is-server.md +37 -0
  147. package/docs/ecosystem/utils/is-standalone-mode.md +49 -0
  148. package/docs/ecosystem/utils/kebab-case.md +42 -0
  149. package/docs/ecosystem/utils/normalize-string.md +83 -0
  150. package/docs/ecosystem/utils/number.md +51 -0
  151. package/docs/ecosystem/utils/pascal-case.md +41 -0
  152. package/docs/ecosystem/utils/prevent-ios-input-zoom.md +72 -0
  153. package/docs/ecosystem/utils/script-loader.md +85 -0
  154. package/docs/ecosystem/utils/sleep.md +65 -0
  155. package/docs/ecosystem/utils/snake-case.md +42 -0
  156. package/docs/ecosystem/utils/swipe-handler.md +97 -0
  157. package/docs/ecosystem/utils/textarea-autogrow.md +47 -0
  158. package/docs/ecosystem/utils/throttle-id.md +54 -0
  159. package/docs/ecosystem/utils/throttle.md +63 -0
  160. package/docs/ecosystem/utils/truthy-filter.md +37 -0
  161. package/docs/ecosystem/utils/types/deep-key-of.md +54 -0
  162. package/docs/ecosystem/utils/types/deep-partial.md +48 -0
  163. package/docs/ecosystem/utils/types/deep-required.md +45 -0
  164. package/docs/ecosystem/utils/types/flatten-object-keys.md +50 -0
  165. package/docs/ecosystem/utils/types/generic-instance-type.md +48 -0
  166. package/docs/ecosystem/utils/types/infer-maybe-ref.md +41 -0
  167. package/docs/ecosystem/utils/upper-first.md +38 -0
  168. package/docs/ecosystem/utils/user-visibility.md +75 -0
  169. package/docs/guide/ai-agents.md +237 -0
  170. package/docs/guide/browser-support.md +88 -0
  171. package/docs/guide/getting-started.md +191 -0
  172. package/docs/guide/global-defaults.md +103 -0
  173. package/docs/guide/maz-ui-provider.md +231 -0
  174. package/docs/guide/migration-v5.md +871 -0
  175. package/docs/guide/resolvers.md +650 -0
  176. package/docs/guide/tailwind.md +483 -0
  177. package/docs/guide/vue.md +286 -0
  178. package/docs/manifest.json +1 -0
  179. package/docs/plugins/aos.md +312 -0
  180. package/docs/plugins/dialog.md +269 -0
  181. package/docs/plugins/toast.md +221 -0
  182. package/docs/plugins/wait.md +78 -0
  183. package/docs/reference/icons.md +46 -0
  184. package/docs/reference/tailwind-tokens.md +191 -0
  185. package/docs/rules.md +57 -0
  186. package/package.json +31 -4
@@ -0,0 +1,513 @@
1
+ ---
2
+ title: "MazSelectCountry"
3
+ description: "MazSelectCountry is a versatile Vue component for selecting countries or languages with built-in internationalization support and customizable display options"
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/components/maz-select-country"
6
+ ---
7
+
8
+ # MazSelectCountry
9
+
10
+ > MazSelectCountry is a versatile Vue component for selecting countries or languages with built-in internationalization support and customizable display options
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import MazSelectCountry from 'maz-ui/components/MazSelectCountry'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/components/maz-select-country
16
+
17
+ **Tip:**
18
+
19
+ This component can be translated globally using the [MazUi](../ecosystem/translations.md) plugin.
20
+
21
+ ## Basic usage
22
+
23
+ The most common use case is selecting a country. The component automatically displays country names in the user's locale with their respective flags.
24
+
25
+ ```vue
26
+ <script setup>
27
+ import { ref } from 'vue'
28
+
29
+ const selectedCountry = ref('FR')
30
+ </script>
31
+
32
+ <template>
33
+ <MazSelectCountry
34
+ v-model="selectedCountry"
35
+ label="Select a country"
36
+ />
37
+ </template>
38
+ ```
39
+
40
+ ## Language selection
41
+
42
+ Configure the component to display languages instead of countries by setting the appropriate `displayNamesOptions`.
43
+
44
+ ```vue
45
+ <script setup>
46
+ import { ref } from 'vue'
47
+
48
+ const selectedLanguage = ref('en')
49
+ </script>
50
+
51
+ <template>
52
+ <MazSelectCountry
53
+ v-model="selectedLanguage"
54
+ label="Select a language"
55
+ :display-names-options="{ type: 'language' }"
56
+ />
57
+ </template>
58
+ ```
59
+
60
+ ## Sizes and colors
61
+
62
+ ```vue
63
+ <template>
64
+ <!-- Sizes -->
65
+ <MazSelectCountry
66
+ v-model="selectedCountry"
67
+ size="sm"
68
+ label="Small"
69
+ />
70
+ <MazSelectCountry
71
+ v-model="selectedCountry"
72
+ size="md"
73
+ label="Medium (default)"
74
+ />
75
+ <MazSelectCountry
76
+ v-model="selectedCountry"
77
+ size="lg"
78
+ label="Large"
79
+ />
80
+
81
+ <!-- Colors -->
82
+ <MazSelectCountry
83
+ v-model="selectedCountry"
84
+ color="primary"
85
+ label="Primary"
86
+ />
87
+ <MazSelectCountry
88
+ v-model="selectedCountry"
89
+ color="secondary"
90
+ label="Secondary"
91
+ />
92
+ <MazSelectCountry
93
+ v-model="selectedCountry"
94
+ color="accent"
95
+ label="Accent"
96
+ />
97
+ </template>
98
+ ```
99
+
100
+ ## Preferred countries
101
+
102
+ You can prioritize certain countries to appear at the top of the list using the `preferredCodes` prop.
103
+
104
+ ```vue
105
+ <template>
106
+ <MazSelectCountry
107
+ v-model="selectedCountry"
108
+ label="European countries first"
109
+ :preferred-codes="['FR', 'DE', 'IT', 'ES', 'GB']"
110
+ />
111
+ </template>
112
+ ```
113
+
114
+ ## Filtering options
115
+
116
+ Control which countries are displayed using `onlyCodes` to show only specific countries, or `ignoredCodes` to exclude certain ones.
117
+
118
+ ```vue
119
+ <template>
120
+ <!-- Only specific countries -->
121
+ <MazSelectCountry
122
+ v-model="selectedCountry"
123
+ label="European countries only"
124
+ :only-codes="['FR', 'DE', 'IT', 'ES', 'GB', 'NL', 'BE', 'AT', 'CH', 'PT']"
125
+ />
126
+
127
+ <!-- Exclude specific countries -->
128
+ <MazSelectCountry
129
+ v-model="selectedCountry"
130
+ label="All except some countries"
131
+ :ignored-codes="['KP', 'SY', 'AF']"
132
+ />
133
+ </template>
134
+ ```
135
+
136
+ ## Custom display options
137
+
138
+ Configure how country/language names are displayed using the `displayNamesOptions` prop, which leverages the browser's `Intl.DisplayNames` API.
139
+
140
+ ```vue
141
+ <template>
142
+ <!-- Short country names -->
143
+ <MazSelectCountry
144
+ v-model="selectedCountry"
145
+ label="Short names"
146
+ :display-names-options="{ type: 'region', style: 'short' }"
147
+ />
148
+
149
+ <!-- Languages with narrow style -->
150
+ <MazSelectCountry
151
+ v-model="selectedLanguage"
152
+ label="Language names (narrow)"
153
+ :display-names-options="{ type: 'language', style: 'narrow' }"
154
+ hide-flags
155
+ />
156
+ </template>
157
+ ```
158
+
159
+ ## Flags source
160
+
161
+ By default, the flags are images of the [flagcdn.com](https://flagcdn.com) CDN: each user's browser requests them from this third party. The `flag-src` prop changes where they come from, in four ways:
162
+
163
+ | Source | `flag-src` | Network |
164
+ | --- | --- | --- |
165
+ | CDN (default) | not set | flagcdn.com |
166
+ | Flags of maz-ui | `loadCountryFlag` from `maz-ui/country-flags` | none (works offline) |
167
+ | Your own files | URL template: `'/flags/{code}.svg'` | your server |
168
+ | Your own function | `(code) => string \| undefined \| Promise<string \| undefined>` | yours |
169
+
170
+ In every case, a flag is only loaded when it becomes visible (the selected country, then the rows of the open list in view), and a code without flag displays the colored badge.
171
+
172
+ ### For the whole app
173
+
174
+ Set it once instead of on every component: the `flag-src` of `MazSelectCountry` and `MazInputPhoneNumber` both default to `defaults.global.flagSrc` (see [Global component defaults](../guide/global-defaults.md)). A `flag-src` set on a component always wins.
175
+
176
+ ```ts
177
+ // Vue: main.ts
178
+ import { loadCountryFlag } from 'maz-ui/country-flags'
179
+ import { MazUi } from 'maz-ui/plugins/maz-ui'
180
+
181
+ app.use(MazUi, {
182
+ theme: { preset: mazUi },
183
+ defaults: {
184
+ global: { flagSrc: loadCountryFlag }, // or a URL template: '/flags/{code}.svg'
185
+ },
186
+ })
187
+ ```
188
+
189
+ ```ts
190
+ // Nuxt: nuxt.config.ts
191
+ export default defineNuxtConfig({
192
+ modules: ['@maz-ui/nuxt'],
193
+ mazUi: {
194
+ flags: 'local', // 'cdn' (default) | 'local' | a URL template: '/flags/{code}.svg'
195
+ },
196
+ })
197
+ ```
198
+
199
+ ### Flags of maz-ui, offline
200
+
201
+ `loadCountryFlag` gives the square flag of a code from the 256 flags of `@maz-ui/icons`, as a `data:image/svg+xml` URL: no request to a third party (nothing to allow for flagcdn.com in your Content Security Policy, the user's IP is not sent to it), and the component works offline (hybrid apps with Capacitor or Cordova, PWAs, intranets).
202
+
203
+ ```vue
204
+ <script lang="ts" setup>
205
+ import { loadCountryFlag } from 'maz-ui/country-flags'
206
+ import { ref } from 'vue'
207
+
208
+ const selectedCountry = ref('FR')
209
+ </script>
210
+
211
+ <template>
212
+ <MazSelectCountry
213
+ v-model="selectedCountry"
214
+ label="Country (flags of maz-ui)"
215
+ :flag-src="loadCountryFlag"
216
+ />
217
+ </template>
218
+ ```
219
+
220
+ How it stays light:
221
+
222
+ - Nothing in maz-ui imports `maz-ui/country-flags`: an app that does not import it has **no flag file at all** in its build.
223
+ - Once imported, your bundler emits **one small chunk per flag** (256 files, from a few hundred bytes to a few kilobytes each). None is preloaded: only the flags displayed are downloaded.
224
+ - The loader itself (a table of 256 dynamic imports, about 4 kB gzipped) goes into the chunk that imports it. To keep it out of your entry chunk, import it on demand (the Nuxt option `flags: 'local'` does it for you):
225
+
226
+ ```ts
227
+ const flagSrc = (code: string) => import('maz-ui/country-flags').then(({ loadCountryFlag }) => loadCountryFlag(code))
228
+ ```
229
+
230
+ **Tip: Content Security Policy**
231
+
232
+ The flags are `data:` URLs: a strict CSP must allow `img-src data:` (already needed by the lazy images of maz-ui).
233
+
234
+ **Tip: PWA precache**
235
+
236
+ Once you use `loadCountryFlag`, the 256 flag chunks are part of your build, so a service worker that precaches every `**/*.js` downloads all of them at install. Keep them (every flag available offline) or exclude them and let them load on demand. With Vite, the chunks are named after their module, `MazFlagSquareFR-[hash].js`:
237
+
238
+ ```ts
239
+ // vite-plugin-pwa
240
+ VitePWA({ workbox: { globIgnores: ['**/MazFlagSquare*.js'] } })
241
+ ```
242
+
243
+ Nuxt names its chunks `_nuxt/[hash].js` only: name the flag chunks yourself to exclude them, e.g. `vite.build.rollupOptions.output.chunkFileNames: chunk => chunk.name.startsWith('MazFlagSquare') ? '_nuxt/flags/[name].[hash].js' : '_nuxt/[hash].js'`, then ignore `**/_nuxt/flags/**`.
244
+
245
+ ### Your own files
246
+
247
+ A URL template, with `{code}` for the lowercase code and `{CODE}` for the uppercase code. The images are lazy loaded like the CDN ones. A missing image displays the badge.
248
+
249
+ ```vue
250
+ <template>
251
+ <!-- public/flags/fr.svg, public/flags/de.svg... -->
252
+ <MazSelectCountry v-model="selectedCountry" flag-src="/flags/{code}.svg" />
253
+
254
+ <!-- another host, uppercase codes -->
255
+ <MazSelectCountry v-model="selectedCountry" flag-src="https://assets.example.com/flags/{CODE}.png" />
256
+ </template>
257
+ ```
258
+
259
+ ### Your own function
260
+
261
+ A function receives the country code of each flag when it becomes visible, and returns the image source (URL or data URL), or `undefined` to display the badge. It can be async: only the flags displayed are loaded.
262
+
263
+ ```vue
264
+ <script lang="ts" setup>
265
+ // One file per flag in your project, loaded on demand (Vite turns this import into one chunk per file)
266
+ function flagSrc(code: string) {
267
+ return import(`./assets/flags/${code.toLowerCase()}.svg?url`)
268
+ .then(module => module.default)
269
+ .catch(() => undefined)
270
+ }
271
+ </script>
272
+
273
+ <template>
274
+ <MazSelectCountry v-model="selectedCountry" :flag-src="flagSrc" />
275
+ </template>
276
+ ```
277
+
278
+ You can also replace the flags entirely with the `selector-flag` and `country-list-flag` slots.
279
+
280
+ ## Without flags
281
+
282
+ Hide country flags using the `hideFlags` prop for a cleaner text-only interface.
283
+
284
+ ```vue
285
+ <template>
286
+ <MazSelectCountry
287
+ v-model="selectedCountry"
288
+ label="Countries without flags"
289
+ hide-flags
290
+ placeholder="Text-only country selection"
291
+ />
292
+ </template>
293
+ ```
294
+
295
+ ## Custom locale
296
+
297
+ Override the default locale to display country/language names in a specific language.
298
+
299
+ ```vue
300
+ <template>
301
+ <!-- Countries in French -->
302
+ <MazSelectCountry
303
+ v-model="selectedCountry"
304
+ label="Pays (French)"
305
+ locale="fr-FR"
306
+ />
307
+
308
+ <!-- Countries in Spanish -->
309
+ <MazSelectCountry
310
+ v-model="selectedCountry"
311
+ label="País (Spanish)"
312
+ locale="es-ES"
313
+ />
314
+ </template>
315
+ ```
316
+
317
+ ## States and validation
318
+
319
+ The component supports all the standard form states for better user experience.
320
+
321
+ ```vue
322
+ <template>
323
+ <MazSelectCountry
324
+ v-model="selectedCountry"
325
+ label="Success state"
326
+ success
327
+ hint="Valid country selected"
328
+ />
329
+
330
+ <MazSelectCountry
331
+ v-model="selectedCountry"
332
+ label="Warning state"
333
+ warning
334
+ hint="Please verify your selection"
335
+ />
336
+
337
+ <MazSelectCountry
338
+ v-model="selectedCountry"
339
+ label="Error state"
340
+ error
341
+ hint="Please select a valid country"
342
+ />
343
+
344
+ <MazSelectCountry
345
+ v-model="selectedCountry"
346
+ label="Disabled state"
347
+ disabled
348
+ hint="Selection is not available"
349
+ />
350
+ </template>
351
+ ```
352
+
353
+ ## Custom options
354
+
355
+ Provide your own list of options instead of using the built-in country/language codes.
356
+
357
+ ```vue
358
+ <script setup>
359
+ import { ref } from 'vue'
360
+
361
+ const selectedCustom = ref()
362
+ const customRegions = [
363
+ { code: 'EUROPE', name: 'Europe' },
364
+ { code: 'ASIA', name: 'Asia' },
365
+ { code: 'AFRICA', name: 'Africa' },
366
+ { code: 'AMERICAS', name: 'Americas' },
367
+ { code: 'OCEANIA', name: 'Oceania' }
368
+ ]
369
+ </script>
370
+
371
+ <template>
372
+ <MazSelectCountry
373
+ v-model="selectedCustom"
374
+ label="Custom regions"
375
+ :options="customRegions"
376
+ hide-flags
377
+ />
378
+ </template>
379
+ ```
380
+
381
+ ## Display code instead of name
382
+
383
+ Show country/language codes in the input field instead of names using the `displayCode` prop.
384
+
385
+ ```vue
386
+ <template>
387
+ <MazSelectCountry
388
+ v-model="selectedCountry"
389
+ label="Display country codes"
390
+ display-code
391
+ placeholder="Shows codes like 'FR', 'US'..."
392
+ />
393
+ </template>
394
+ ```
395
+
396
+ ## Advanced configuration
397
+
398
+ Combine multiple features for complex use cases, such as business applications requiring specific country lists with custom styling.
399
+
400
+ ```vue
401
+ <template>
402
+ <MazSelectCountry
403
+ v-model="selectedCountry"
404
+ label="Business countries"
405
+ color="primary"
406
+ size="lg"
407
+ :preferred-codes="['US', 'GB', 'DE', 'FR', 'CA']"
408
+ :ignored-codes="['AQ', 'BV', 'HM']"
409
+ :search-threshold="2"
410
+ display-code
411
+ success
412
+ hint="Primary business regions prioritized"
413
+ />
414
+ </template>
415
+ ```
416
+
417
+ ## How it works
418
+
419
+ The `MazSelectCountry` component is built on top of `MazSelect` and leverages the powerful `useDisplayNames` composable, which uses the browser's native `Intl.DisplayNames` API for internationalization.
420
+
421
+ ### Key features:
422
+
423
+ - **Automatic localization**: Country and language names are displayed in the user's locale
424
+ - **Built-in search**: Users can quickly find countries by typing
425
+ - **Flag integration**: Automatic flag display using country codes, from the flagcdn.com CDN, the flags of maz-ui (offline) or your own files
426
+ - **Flexible filtering**: Support for preferred, ignored, or specific country lists
427
+ - **Custom options**: Override default behavior with custom data
428
+ - **Accessibility**: Full keyboard navigation and screen reader support
429
+
430
+ ### useDisplayNames composable
431
+
432
+ The component uses the `useDisplayNames` composable internally, which provides:
433
+
434
+ ```typescript
435
+ // Get display name for a single code
436
+ const displayName = getDisplayName('FR', {
437
+ locale: 'en-US',
438
+ type: 'region'
439
+ })
440
+
441
+ // Get all display names with filtering
442
+ const allCountries = getAllDisplayNames({
443
+ locale: 'en-US',
444
+ codesType: 'country',
445
+ preferred: ['US', 'GB', 'FR'],
446
+ exclude: ['AQ']
447
+ })
448
+ ```
449
+
450
+ This ensures consistent internationalization across your application while providing maximum flexibility for different use cases.
451
+
452
+ ## MazSelectCountry API
453
+
454
+ `import MazSelectCountry from 'maz-ui/components/MazSelectCountry'`
455
+
456
+ ### Props
457
+
458
+ - `id` (`string`): Id of the component.
459
+ - `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): Color of the component.
460
+ - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `md`): Size of the component.
461
+ - `preferred-codes` (`Option["code"][]`): Preferred countries to display.
462
+ - `ignored-codes` (`Option["code"][]`): Ignored countries to display.
463
+ - `only-codes` (`Option["code"][]`): Only countries to display.
464
+ - `list-position` (`MazPopoverPosition`, default: `'auto'`): Position of the list.
465
+ - `hide-flags` (`boolean`): Hide flags.
466
+ - `flag-src` (`MazCountryFlagSrc`, default: `undefined (flags from flagcdn.com)`): Source of the flags, instead of the flagcdn.com CDN: - a URL template with the code, `{code}` (lowercase) or `{CODE}` (uppercase): `/flags/{code}.svg` - a function giving the image source of a code (URL or data URL), called when the flag becomes visible, or `undefined` to display the code in a badge Use `loadCountryFlag` from `maz-ui/country-flags` for the flags of `@maz-ui/icons`, without any request to a third party. Can be set for the whole app with the `defaults.global.flagSrc` option of the MazUi plugin.
467
+ - `search` (`boolean`, default: `true`): Display search input in options list.
468
+ - `show-code-in-list` (`boolean`, default: `false`): Show code on list.
469
+ - `locale` (`string`, default: `locale defined within the maz-ui plugin or browser locale or en-US`): Locale.
470
+ - `success` (`boolean`): Success state.
471
+ - `error` (`boolean`): Error state.
472
+ - `warning` (`boolean`): Warning state.
473
+ - `display-code` (`boolean`)
474
+ - `search-threshold` (`number`, default: `0.75`): Search threshold.
475
+ - `translations` (`Partial<{ searchPlaceholder: string; }>`, default: `MazUiTranslationsNestedSchema['selectCountry']`): Translations.
476
+ - `hint` (`string`): Hint message displayed.
477
+ - `options` (`Option[]`): Options.
478
+ - `display-names-options` (`DisplayNamesOptions`, default: `{ type: "region", languageDisplay: "standard", fallback: "code", style: "long" }`): Display name type.
479
+ - `codes-type` (`CodesType`, default: `defined by displayNamesOptions.type (if 'region', 'country' is used, otherwise 'iso')`): Codes type. Values: `'iso'`, `'bcp'`, `'country'`, `'all'` (non exhaustive).
480
+ - `open` (`boolean`, default: `false`): Open the select.
481
+ - `model-value` (`Option["code"]`, `v-model`): The value of the select.
482
+ - `disabled` (`boolean`): Disable the component.
483
+ - `block` (`boolean`): The input will be displayed in full width.
484
+ - `placeholder` (`string`): The placeholder of the select.
485
+ - `required` (`boolean`): Make the input required in the form.
486
+ - `label` (`string`): The label of the select.
487
+ - `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
488
+ - `transition` (`string`, default: `'scale-fade'`): The transition name of the panel list options.
489
+ - `prefer-position` (`MazPopoverPreferPosition`, default: `'bottom-start'`): The prefer position of the list.
490
+ - `fallback-position` (`MazPopoverFallbackPosition`, default: `'top-start'`): The fallback position of the list.
491
+ - `top-label` (`string`): Static label displayed above the input field. Unlike the floating label, this remains fixed.
492
+ - `autocomplete` (`string`, default: `'off'`): The autocomplete attribute of the input.
493
+ - `option-value-key` (`string`, default: `"code"`): The key of the option value.
494
+ - `option-label-key` (`string`, default: `"name"`): The key of the option label.
495
+ - `option-input-value-key` (`string`, default: `"name"`): The key of the option input value.
496
+ - `item-height` (`number`): The height of the option list item.
497
+ - `max-list-height` (`number`, default: `240`): The max height of the option list.
498
+ - `max-list-width` (`number`, default: `250`): The max width of the option list.
499
+ - `min-list-height` (`number`): The min height of the option list.
500
+ - `min-list-width` (`number`, default: `200`): The min width of the option list.
501
+ - `format-input-value` (`((value: Option["code"]) => string)`): The function to format the input value.
502
+
503
+ ### Events
504
+
505
+ - `@update:model-value` (payload: `value?: Option["code"] | undefined`): Emitted when the model value changes
506
+
507
+ ### Slots
508
+
509
+ - `#selector-flag`: Country selector flag Bindings: `countryCode: Option["code"]` (current selected country code - Ex: `"FR"`).
510
+ - `#no-results`
511
+ - `#country-list-flag`: Country list flag Bindings: `option: Option` (country data), `isSelected: boolean` (`true` if option is selected).
512
+ - `#country-list-code` Bindings: `option: Option`, `isSelected: boolean`.
513
+ - `#country-list-name` Bindings: `option: Option`, `isSelected: boolean`.