use-sorted-locale

Sort strings locale-aware with Intl.Collator.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useSortedLocale } from "@vizejs/composable/use-sorted-locale";

Try it

Sort names for each language

Sort strings with the reader's collation rules instead of code point order.

Open the interactive example

What to observe: German sorts Ärla and Örjan next to A and O. Choose Swedish to move them after Zoe, where Swedish readers expect Ä and Ö.

The options can be a computed ref, so changing the locale rebuilds the Intl.Collator. Pass key to sort objects by one of their fields.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { computed, ref } from "vue";
import { useSortedLocale } from "@vizejs/composable/use-sorted-locale";

const locale = ref("de-DE");
const names = ["Zoe", "Ärla", "Anna", "Oskar", "Örjan"];
const { sorted } = useSortedLocale(
  names,
  computed(() => ({ locale: locale.value })),
);
</script>

<template>
  <div class="composable-example">
    <p>Sort names the way readers of each language expect.</p>
    <label>
      Sort for
      <select v-model="locale">
        <option value="de-DE">German</option>
        <option value="sv-SE">Swedish</option>
      </select>
    </label>
    <output aria-live="polite">{{ sorted.join(", ") }}</output>
  </div>
</template>

Runtime contract

API

useSortedLocale

Sort strings locale-aware with Intl.Collator.

function useSortedLocale( items: MaybeRefOrGetter<readonly string[]>, options?: MaybeRefOrGetter<UseSortedLocaleOptions<string>>, ): SortedLocaleControls<string>

useSortedLocale

Sort any items locale-aware by a string key with Intl.Collator.

function useSortedLocale<Item>( items: MaybeRefOrGetter<readonly Item[]>, options: MaybeRefOrGetter< UseSortedLocaleOptions<Item> & { readonly key: (item: Item) => string } >, ): SortedLocaleControls<Item>

useSortedLocale

Sort items with locale-aware collation (Intl.Collator): "ä" sorts next to "a" in German but after "z" in Swedish, and numeric: true orders "item 10" after "item 9". The result is a new, stable-sorted array recomputed when the items, options, or locale change; the source array is never mutated. Invalid options surface as the platform RangeError. Derived state only: safe and deterministic on the server when the locale is explicit.

function useSortedLocale<Item>( items: MaybeRefOrGetter<readonly Item[]>, options: MaybeRefOrGetter<UseSortedLocaleOptions<Item>> = {}, ): SortedLocaleControls<Item>

const { sorted } = useSortedLocale(users, { key: (user) => user.name, locale: "de", sensitivity: "base" });

Types

UseSortedLocaleOptions

Options for useSortedLocale.

SortedLocaleControls

Reactive locale-aware sorting returned by useSortedLocale.