selectWoo – An accessible replacement for select2

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.

8 responses to “selectWoo – An accessible replacement for select2”

  1. Hello,

    I really don’t know what the reasoning for this move was? Is there really a need to have a custom fork? What will happen in the future, when select2 is back on track?

    Wouldn’t it have been better to improve select2 and create pull requests over there? (I don’t see any issues or PRs from claudiulodro in the select2 repository)

    And have you contacted the maintainers about the current status of select2? (Maybe there is a reason for this)
    All 3 people within the select2 repository are quite active at Github, so this project propably isn’t “dead” or “abondoned” how it reads in your article. Maybe you should have asked theme, before.

    (Nevertheless it would be really sad, if select2 really wouldn’t be activily developed anymore, maybe WooCommerce should just overtake it 😉


    1. Select2 has not had any commits since February. With a fork we can at least get things merged in to meet our own schedule, rather than waiting/relying on others or running custom versions. There are other benefits too such as allowing our version to be namespaced to avoid conflicts in WP Admin.

      The fork is public. Our changes can be merged back, when/if the project picks up again.

      1. I was not aware that select2 was unmaintained and you tried merging before creating a fork. I feel your pain…

        Unfortunately, many users will not pick up the new (better) branch because they will probably be unaware of it (despite this blog post). Unfortunately, this happens far too often in FOSS land: Abandoned repos and for new and casual users it’s hard to find out about the newer, better, up-to-date fork…

        FWIW, npm has a policy here to allow friendly takeovers of abandoned projects.

        I use select2 outside of WordPress projects in contexts for a11y is very important. So I very much welcome the changes and will use it in the future. But I just use yarn/npm (plus a builder like grunt/gulp/webpack) as most do these days. So if you update the package on it would benefit most users.

        Here’s a story about how such a friendly takeover would go:

        Let’s keep FOSS sane and healthy 🙂

  2. Really great work!

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

    Have you considered sending a PR to the original select2 repo? I don’t think we need more fragmentation… If I find a bug in selectWoo which is also present in select2 then two PRs are needed. From former examples, both projects diverge more and more which is not in the interest of the users :-/ I think a fork should only always be the last (but legitimate) approach.

    1. There are over 100 PRs in select2 repo unmerged. Some of these we actually need, so with the fork we’re free to merge these as needed. The accessibility issues are hurting users today, so we cannot really afford to wait.

      Regardless, namespacing select2 in WP Admin is of benefit to avoid conflicts like we saw with 3.0.

  3. josephpmurray Avatar

    Thanks so much! We’ll be trying this out with CiviCRM in the coming weeks, which integrates not only with WordPress but also Drupal and Joomla.

    1. That seems to be a separate thing not necessarily caused by a bug in select2. It could be something WooCommerce is doing when initializing select2. I’ll investigate.

Leave a Reply

Your email address will not be published. Required fields are marked *