Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Universal Language Selector jQuery library

Test status Lint status

This is a Wikimedia Foundation project.

Universal Language Selector

Quick start

git clone


The quick and easy way to learn usage of jquery.uls is trying out the examples/index.html in webserver. Try it online at

The jquery.uls provides a jQuery extension $.fn.uls that can be attached to a trigger element. When you click on the trigger element, the language selector is shown.

The trigger can be a link, button or any valid jQuery element.


$( '.uls-trigger' ).uls();

To use the selected language, you need define a selection handler:

$( '.uls-trigger' ).uls( {
  onSelect: function( language ) {
  // language is a IETF language tag in lowercase, for example: en, fi, ku-latn
  // Your selection handler code goes here.
} );

You can provide a quick list of likely useful languages, for example based on Geo IP or recently selected languages:

$( '.uls-trigger' ).uls( {
  onSelect: function( language ) { ... },
  quickList: [ 'en', 'ml', 'hi' ] // Can be a function returning an array too.
} );

jquery.uls knows about 500 languages. You can specify a subset of those languages:

$( '.uls-trigger' ).uls( {
  onSelect: function( language ) { ... },
  languages: { languageCode1: languageName, languageCode2: languageName2, .... },
} );

All options

Option Description
left DEPRECATED: use onPosition
top DEPRECATED: use onPosition
onSelect Callback function when user selects a language.
onCancel Callback function when the dialog is closed without selecting a language.
onReady Callback function when ULS has initialized.
onVisible Callback function when ULS dialog is shown.
onPosition Callback for positioning the dialog. It should return an object with any of the keys top, right, bottom and left.
languages List of selectable languages. Defaults to all known languages.
menuWidth Override the automatic choice of menu width. One of narrow, medium, wide (1, 2, 4 columns respectively).
ulsPurpose A string that will identify this instance of ULS. It's useful if you have several instances of ULS in your web application and you want to have a unique identifier for each of them.
quicklist List of suggested languages. Defaults to empty list.
showRegions Regions to be shown in the language selector. Defaults to [ WW, AM, EU, ME, AF, AS, PA ]
languageDecorator Callback function to be called when a language link is prepared - for custom decoration. Arguments: (a) the $language - the language link jQuery object (b) languageCode. The function can do any styling, changing properties etc on the passed link. See examples/decorator.html for example usage.
noResultsTemplate A jQuery object or a function that returns a jQuery object. This will be used as the template to display when no results found from the search. The function will receive the current search query as argument
itemsPerColumn Number of languages per column. Default is 8
groupByRegion Whether to group languages by the regions: true of false. Default value depends on the menu width.
searchAPI API URL. Parameter query with the user query is appened to it.


jquery.uls has an elaborative language information collection and it is based on It knows about

  1. The script in which a language is written.
  2. The script code
  3. The language code
  4. The regions in which the language is spoken
  5. The autonym - language name written in its own script
  6. The directionality of the text

With all these information the search becomes very effective. An advanced usage of jquery.uls can be tried out from Wikimedia sites. For example, see the language icon at the top of or the cog icon near to the languages list in Wikipedia in any language.

More details

How to build and test jquery.uls

First, get a copy of the git repo by running:

git clone git://

Make sure you have grunt installed by testing:

grunt -version

If not, run:

npm install

To run tests locally, run grunt test. This will run the tests in PhantomJS.

You can also run the tests in a browser by navigating to the test/ directory, but first run grunt to install the submodules.

Updating language-data

From the main repo directory, run:


Coding style

Please follow MediaWiki coding conventions


Universal Language Selector



Code of conduct





No releases published


No packages published