- Common widgets, layouts, and dialogs
- Classes, elements, and mixins to create custom interfaces
- Internationalization and localization, like right-to-left (RTL) languages support
- Built-in icons
- Accessibility features
It is the standard library for Web products at the Wikimedia Foundation, having been originally created for use by VisualEditor.
The library is available on npm. To install:
$ npm install oojs-ui
Once installed, include the following scripts and styles to get started:
Loading the library
While the distribution directory is chock-full of files, you will normally load only the following three:
oojs-ui.js, containing the full library;
- One of
oojs-ui-apex.css, containing theme-specific styles; and
- One of
oojs-ui-apex.js, containing theme-specific code
You can load additional icon packs from files named
The remaining files make it possible to load only parts of the whole library.
Furthermore, every CSS file has a right-to-left (RTL) version available, to be used on pages using right-to-left languages if your environment doesn't automatically flip them as needed.
Found a bug or missing feature? Please report it in our issue tracker Phabricator!
We are always delighted when people contribute patches. To setup your development environment:
Clone the repo:
$ git clone https://gerrit.wikimedia.org/r/oojs/ui oojs-ui
Move into the library directory:
$ cd oojs-ui
Install composer and make sure running
composerwill execute it (e.g. add it to
$PATHin POSIX environments).
Install dev dependencies:
$ npm install
Build the library (you can alternatively use
grunt quick-buildif you don't need to rebuild the PNGs):
$ grunt build
You can see a suite of demos in
$ npm run-script demos
You can also copy the distribution files from the dist directory into your project.
- If you've found a bug, or wish to request a feature raise a ticket on Phabricator.
- To submit your patch, follow the "getting started" quick-guide. We try to review patches within a week.
composer testlocally before pushing changes. SVG files should be squashed in advance of committing with SVGO using
svgo --pretty --disable=removeXMLProcInst --disable=cleanupIDs <filename>.
A new version of the library is released most weeks on Tuesdays.
Get updates, ask questions and join the discussion with maintainers and contributors:
- Join the Wikimedia Developers mailing list, wikitech-l.
- Chat with the maintainers on
- Ask questions on StackOverflow.
- Watchlist the documentation on MediaWiki to stay updated.
We use the Semantic Versioning guidelines.
Releases will be numbered in the following format:
$ cd path/to/oojs-ui/ $ git remote update $ git checkout -B release -t origin/master # Ensure tests pass $ npm install && composer update && npm test && composer test # Avoid using "npm version patch" because that creates # both a commit and a tag, and we shouldn't tag until after # the commit is merged. # Update release notes # Copy the resulting list into a new section at the top of History.md and edit # into five sub-sections, in order: # * Breaking changes # * Deprecations # * Features # * Styles # * Code $ git log --format='* %s (%aN)' --no-merges --reverse v$(node -e 'console.log(require("./package.json").version);')...HEAD | grep -v "Localisation updates from" | sort $ edit History.md # Update the version number $ edit package.json $ git add -p $ git commit -m "Tag vX.X.X" $ git review # After merging: $ git remote update $ git checkout origin/master $ git tag "vX.X.X" $ npm run publish-build && git push --tags && npm publish