The select2 library makes it simple for anyone to add full-featured, good-looking dropdown menus to their site. According to Wappalyzer, at least 850,000 websites are currently using select2. WooCommerce uses it in many places to enhance the look and usability of stores.

It is an excellent and popular library for making custom dropdown menus, but one of the biggest and longest-running problems with it has been its lack of accessibility. The fancy dropdowns generated by select2 simply do not work well with screen-reading software. The WooCommerce team has a strong commitment to backwards compatibility and to making the web accessible, but the select2 library has been unmaintained since the beginning of the year. For these reasons, we have forked the select2 library and improved its accessibility in a new release we’re calling selectWoo.

selectWoo is a backwards-compatible, drop-in replacement for select2 with improved accessibility.

Getting Started

To get a copy of selectWoo, you can download the beta release here. The selectWoo JavaScript and CSS files are in the “dist” subfolder. There are two versions of each file: one called “select2” and one called “selectWoo”. Both files are the exact same, so you can use either depending on your preference.

You can use selectWoo the exact same way that you would use select2. Everything works the same; it’s just more accessible.

Converting existing select2 applications to selectWoo

If you are already using select2, all you have to do is replace the select2.js file you are currently using with the new select2.js file from selectWoo and you should be good to go. All code is backwards-compatible and everything should function the same.

selectWoo can also run in parallel with other versions of select2. This solves a common problem in WordPress where two plugins will be using different versions of select2, so one plugin breaks. If you want to take advantage of this safeguard you will have to initialize elements with $('...').selectWoo() instead of $('...').select2(). If you don’t need this feature, you can initialize dropdowns using either of the methods.

If you are using a custom CSS stylesheet for styling select2 elements, you may need to update CSS selectors that style ‘aria-selected’ elements to style ‘data-selected’ elements instead. This is due to a design flaw that had to be corrected from the original select2 library where ‘aria-selected’ attributes were not being used properly.

Call for accessibility testing

selectWoo has improved accessibility, but it is not perfect in every screen reader yet. We need your help ensuring selectWoo works great for all users.

There are two ways you can help us test selectWoo so that we can make it accessible for everyone.

  1. Go to this test page. Try out the different example pages using a screen reader and verify they work correctly in your screen-reading software.

  2. Download the WooCommerce master branch and verify dropdowns are accessible in WooCommerce. WooCommerce 3.2 has not been released yet, so do not do this on a production site. Do this on a local or staging site. selectWoo is used on the checkout page when selecting your country and state. It is also used in the WooCommerce settings pages for all of the dropdown settings.

Found an issue?

Please post any issues you find as a comment in this GitHub issue. Please include where you noticed accessibility problems, the screen-reading software you used, your operating system, and your browser.