Navigation Back to home

LocalePicker

A beautiful LocalePicker that can make your life easier and also looks good.

Import
the javascript logo
import { LocalePicker } from "@schukai/monster/source/components/accessibility/locale-picker.mjs";
Source
the git logo
Package
the npm logo
Since
3.97.0

Introduction

The Locale Picker is a versatile web component designed to enhance user experience by facilitating seamless language selection. It serves as a key element for creating a more interactive and inclusive browsing experience. Whether you are building a basic website or a complex enterprise-level application, the Locale Picker ensures smooth and efficient language preferences for users.

Key Features

  • Dynamic interaction: Detects the user's language preferences and provides options for switching to a preferred language, making the web experience more user-centric and intuitive.
  • Customizable appearance: Allows developers to modify its visual design using part attributes, ensuring it integrates seamlessly with your application's design.
  • Accessibility: Built with accessibility in mind, it supports keyboard navigation, screen readers, and focus management, ensuring all users can interact effectively.
  • Responsive design: The component adapts to different layouts and screen sizes, making it suitable for both desktop and mobile applications.
  • Programmatic control: Offers lifecycle methods such as connectedCallback and configurable features like features.removeOnSelected, giving developers greater flexibility to manage the component.

How It Works

The Locale Picker inspects the languages set in the client’s browser (navigator.languages) and compares them with the language of the current document, as defined in the <html lang="de"> attribute (e.g., de in this example).

If the document’s language matches one of the client’s preferred languages, the control remains hidden, and no changes are made. However, if the document’s language does not match the client’s settings, the control becomes visible.

Customization Example

The appearance of the control can be customized using CSS. For example:


<monster-locale-picker
        style="position: absolute; left: 0; top: 0; background-color: greenyellow; border: 1px solid black; padding: 10px;">
</monster-locale-picker>

Language Options

The client’s primary language is displayed on the button by default. If multiple languages are available, a dropdown menu will also appear. The available language versions of the document are derived from the document itself, specifically through the <link hreflang> attributes. For example:


<link hreflang="de" title="Deutsch" href="/de.html" rel="alternate">
<link hreflang="fr" title="Français" href="/fr.html" rel="alternate">

This approach has the added benefit of providing additional links for search engines, which is advantageous for SEO.

Improving the User Experience

The Locale Picker elevates the user experience by offering an easy and visually intuitive way to switch between languages. Its dynamic interaction capabilities ensure that users are presented with relevant language options based on their preferences, and its accessible design makes it inclusive for all users.

With features like real-time language detection and support for multiple options, the component ensures users have a responsive and engaging experience. Studies have shown that personalized language options can significantly enhance user satisfaction and engagement.

Efficiency in the Development Process

Integrating the Locale Picker into your development process is straightforward and efficient. Its modular design, compatibility with Monster.js standards, and use of standard web technologies ensure it works seamlessly with your existing tools and workflows.

By leveraging the Shadow DOM and exported part attributes, developers can quickly customize and deploy the component while maintaining encapsulation and preventing external interference. This reduces development time and ensures consistency across different environments.

Simple Example

In this simple example, the language selector is seamlessly inserted into the DOM structure.

For the control to function properly, if the document's language is English, the html tag must include the attribute lang="en". Additionally, the alternative languages must be specified using link tags. This is done by adding the hreflang attribute to the HTMLLinkElement.

If you want to display the element as a popup or as a layer over other elements, you can easily achieve this using CSS. Simply define the following styles. You can also apply them through a separate CSS class: style="position: absolute; left: 0; top: 0; background-color: greenyellow; border: 1px solid black; padding: 10px;"

Javascript

import '@schukai/monster/source/components/accessibility/locale-picker-simple.mjs';

HTML

<monster-locale-picker></monster-locale-picker>

Stylesheet

/** no additional stylesheet is defined **/

Reset Selection

In this example, we demonstrate how to reverse a decision that has already been made. This is useful, for instance, when you want to give the user the option to undo an incorrect decision made by mistake.

The decision can easily be reversed by calling the reset method of the monster-locale-picker element.

Important Note: In this guide, we’re only simulating the behavior as there are no other language versions of the guide available. Clicking the switch to English button will therefore result in an error.

Javascript

import '@schukai/monster/source/components/accessibility/locale-picker-simple.mjs';

document.getElementById("reset-button").addEventListener("click", function() {
    document.getElementById("locale-picker").reset();
});

HTML

<monster-locale-picker id="locale-picker"></monster-locale-picker>


<button id="reset-button">reset decision</button>

Stylesheet

/** no additional stylesheet is defined **/

Component Design

This component is built using the Shadow DOM, which allows it to encapsulate its internal structure and styling. By using a shadow root, the component's internal elements are isolated from the rest of the webpage, ensuring that external styles or scripts cannot accidentally modify its internal layout or behavior.

Shadow DOM and Accessibility

Since the component is encapsulated within a shadow root, direct access to its internal elements is restricted. This means that developers cannot manipulate or style these elements from outside the component. The Shadow DOM helps maintain consistency in the design and behavior of the component by preventing external interference.

Customizing Through Exported Parts

While the Shadow DOM restricts direct access to the component's internal structure, customization is still possible through exported parts. Specific parts of the component are made accessible for styling by being explicitly marked for export. These exported parts can be targeted and customized using CSS, allowing you to modify the appearance of the component without compromising its encapsulation.

Available Part Attributes

  • control: This part represents the main control area, which includes the headline, buttons, and dropdown for language selection. Use this to style the layout and general appearance of the component.
  • headline: Represents the headline text, which is customizable for different locales.
  • container: Represents the container for buttons and the language dropdown.

Below is an example of how to use CSS part attributes to customize different parts of the Locale Picker.


monster-locale-picker::part(control) {
    background-color: #f9f9f9;
    padding: 16px;
}

monster-locale-picker::part(headline) {
    font-size: 1.5em;
    color: #333;
}

monster-locale-picker::part(container) {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
    gap: 10px;
}

Explanation of the Example

  • monster-locale-picker::part(control): Styles the main control area with a light background and padding for better visual separation.
  • monster-locale-picker::part(headline): Adjusts the font size and color of the headline to emphasize its importance.
  • monster-locale-picker::part(container): Defines a grid layout for the buttons and dropdown, ensuring a structured and responsive design.

Accessibility

Accessibility is a key consideration in the design of this component. By following best practices for web accessibility, the component ensures that users of all abilities can interact with it effectively. This includes support for keyboard navigation, screen readers, and other assistive technologies to provide an inclusive user experience.

HTML Structure

<monster-locale-picker></monster-locale-picker>

JavaScript Initialization

const element = document.createElement('monster-locale-picker');
document.body.appendChild(element);

Exported

LocalePicker

Derived from

CustomElement

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomElement.

Option
Type
Default
Description
templates
object
Template definitions
templates.main
string
undefined
Main template
labels
object
Label definitions
labels.headline
string
Welcome to our Website
Headline
labels.text
string
This page is currently displayed in ${currentLabel}. However, we also offer this page in your preferred language. Would you like to switch?
Text
labels.button-label
string
undefined
Button label
labels.button-no-thanks
string
undefined
Button no thanks
labels.headline-other
string
undefined
Headline other languages
callbacks.getTranslation
function
undefined
Callback to get the translation for the labels
features
object
Features
features.removeOnSelected
boolean
false
Remove the element when a language is selected
features.showAlways
boolean
false
Show the element always
disabled
boolean
false
Disabled state

  • since
  • deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomElement.

  • data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
  • data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomElement.

Behavioral methods

hide()
Hides the locale picker.
reset()
Resets the locale picker by removing the stored value from the local storage.
show()
Shows the locale picker.

Static methods

[instanceSymbol]()
This method is called by the instanceof operator.
getCSSStyleSheet()
Returns
  • {CSSStyleSheet[]}
getTag()
Returns
  • {string}

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

connectedCallback()
Returns
  • {void}
Lifecycle method that is called when the custom element is appended into a document-connected element. Invokes the parent class's connectedCallback method and retrieves the user's preferred language. Logs the preferred language to the console.

Other methods

[assembleMethodSymbol]()
Returns
  • {LocalePicker}
[updaterTransformerMethodsSymbol]()
Returns
  • {object}: object containing transformer methods for internal use.
Private method that provides a mapping of transformer methods keyed by their names. These transformer methods define custom transformations for given input values.

Events

This component does not fire any public events. It may fire events that are inherited from its parent classes.

The current width of the area is too small to display the content correctly.