Skip to main content
USWDS + Tailwind

Language selector

Help visitors find content in their preferred language with language selector toggles and dropdowns.

Examples

Toggle

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
HTML
<a href="#" class="inline-block rounded-sm font-bold leading-none text-white px-5 py-3 bg-blue-60v hover:bg-blue-warm-70v active:bg-blue-warm-80v focus:outline-4 focus:outline-offset-4 focus:outline-blue-40v">
  <span lang="es">Español</span>
</a>

The dropdown example uses this JavaScript initializer:

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
HTML
<div class="space-y-8">


  <section>
    <div data-scope="dropdown" data-part="root">
      <button
        data-scope="dropdown" data-part="trigger"
        class="rounded-sm font-bold leading-none cursor-pointer text-white px-5 py-3 bg-blue-60v hover:bg-blue-warm-70v active:bg-blue-warm-80v focus:outline-4 focus:outline-offset-4 focus:outline-blue-40v"
      >
        Languages
      </button>
      <div
        data-scope="dropdown" data-part="content"
        class="outline-hidden bg-blue-warm-80v w-60 divide-y divide-gray-cool-10 z-30"
      >
        <div data-scope="dropdown" data-part="item"><a
          href="#"
          class="block text-white p-2 hover:underline focus:outline-4 focus:-outline-offset-4 focus:outline-blue-40v"
        >
          <span lang="ar">
            <strong>العربية</strong>
            (Arabic) </span>
        </a></div>
        <div data-scope="dropdown" data-part="item"><a
          href="#"
          class="block text-white p-2 hover:underline focus:outline-4 focus:-outline-offset-4 focus:outline-blue-40v"
        >
          <span lang="zh">
            <strong>简体字</strong>
            (Chinese - Simplified) </span>
        </a></div>
        <div data-scope="dropdown" data-part="item"><a
          href="#"
          class="block text-white p-2 hover:underline focus:outline-4 focus:-outline-offset-4 focus:outline-blue-40v"
        >
          <span lang="en">
            <strong>English</strong>
          </span>
        </a></div>
        <div data-scope="dropdown" data-part="item"><a
          href="#"
          class="block text-white p-2 hover:underline focus:outline-4 focus:-outline-offset-4 focus:outline-blue-40v"
        >
          <span lang="es">
            <strong>Español</strong>
            (Spanish) </span>
        </a></div>
        <div data-scope="dropdown" data-part="item"><a
          href="#"
          class="block text-white p-2 hover:underline focus:outline-4 focus:-outline-offset-4 focus:outline-blue-40v"
        >
          <span lang="fr">
            <strong>Français</strong>
            (French) </span>
        </a></div>
        <div data-scope="dropdown" data-part="item"><a
          href="#"
          class="block text-white p-2 hover:underline focus:outline-4 focus:-outline-offset-4 focus:outline-blue-40v"
        >
          <span lang="it">
            <strong>Italiano</strong>
            (Italian) </span>
        </a></div>
        <div data-scope="dropdown" data-part="item"><a
          href="#"
          class="block text-white p-2 hover:underline focus:outline-4 focus:-outline-offset-4 focus:outline-blue-40v"
        >
          <span lang="ru">
            <strong>Pусский</strong>
            (Russian) </span>
        </a></div>
      </div>
    </div>
  </section>


</div>

Component API

Initialization

Run after the component markup exists:

import { dropdownInit } from '@uswds-tailwind/compat/dropdown'


dropdownInit()

Only the Dropdown example needs initialization. Toggle uses ordinary links.

Anatomy

Set authored attributes in your HTML. The component manages generated attributes. Types describe HTML attribute values.

root

Wraps the disclosure.

Attribute Type Description
data-scope "dropdown" Authored. Identifies the component scope.
data-part "root" Authored. Identifies this part.
data-state "open" | "closed" Generated. "open" or "closed"; use for styling.

trigger

A native button with descriptive text.

Attribute Type Description
data-part "trigger" Authored. Identifies this part.
data-state "open" | "closed" Generated. "open" or "closed"; use for styling.
aria-expanded "true" | "false" Generated. Whether the content is expanded.
aria-controls ID reference Generated. ID of the associated content.

content

Contains the language links.

Attribute Type Description
data-part "content" Authored. Identifies this part.
data-state "open" | "closed" Generated. "open" or "closed"; use for styling.
hidden boolean attribute Generated. Present when closed.

item

Wraps each link. Links follow their native destinations.

Attribute Type Description
data-part "item" Authored. Identifies this part.
data-value string Authored. Identifies the selected item in onItemSelect; falls back to id.

Configuration

Pass these JavaScript options to the instance constructor or factory. Dropdown always starts closed. It does not accept open, defaultOpen, or onOpenChange.

Option Description
id, ids Customize the instance identifier and generated element IDs.

Methods

Method Returns Description
open() Promise<void> Requests opening.
close() Promise<void> Requests closing.
destroy() void Stops the machine and clears the lookup. 
import { Dropdown } from '@uswds-tailwind/compat/dropdown'


const dropdown = Dropdown.getOrCreateInstance(
  '[data-scope="dropdown"][data-part="root"]',
)


await dropdown.open()

Promises settle the queued update, not CSS transitions.

See initialization and cleanup.

Callbacks

Callback Payload When it runs
onItemSelect { value: string } A link with an item value is selected.

Pass callbacks in instance options. These are JavaScript functions, not emitted DOM events.

Accessibility

  • Supply real href, lang, and hreflang values as appropriate. Selection does not translate the page automatically.
  • Preserve native link focus and navigation. This is a disclosure for links, not an application menu.