Menu Search
Jump to the content X X
SmashingConf London Avatar

We use ad-blockers as well, you know. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. our upcoming SmashingConf London, dedicated to all things web performance.

Improving The UX Of Names With Vocalizer.js

We have all encountered names that are difficult to pronounce. Having a challenging name myself, I get different pronunciations of my first name, Atif, all the time. In order to solve my own naming problem, I built a Javascript plugin called Vocalizer. In this article, I will introduce what Vocalizer is and a few different ways to use it.

How It Started Link

Earlier this year, I redesigned my portfolio website. During this process, I decided to add a feature that educated visitors on how to say my name. One day, I opened the “Voice Memos” app on my iPhone, tapped “Record”, and asked my wife to say my first name. Then, I embedded a small button onto the landing page after my first name. Clicking on that button would play the audio file of my name.

The audio pronunciation button that I added to my website.1

The audio pronunciation button that I added to my website (Large preview2)

After launching the website, I received a few emails and tweets calling out the audio feature. I even attended a few conferences and meetups where people pronounced my name the right way. A few people expressed interest in implementing the pronunciation feature on their own websites.

Further Reading on SmashingMag: Link3

Over the next few weeks, I spent time converting my singular implementation into a reusable plugin. Before publicly releasing it, I stumbled upon a company called <ahref=””>NameShouts, which is an audio-based pronunciation tool with a repository of over 70,000 name pronunciations. I reached out to them for access to their API, implemented it into my plugin, and open-sourced it.

How To Use Vocalizer Link

Vocalizer is a simple, lightweight JavaScript plugin that facilitates the accessibility of difficult to pronounce names. If you’re someone who is unsure of how to say a certain name, Vocalizer shows you how. Or, if you’re someone with an unfamiliar name, Vocalizer shows others how to pronounce it.

A closer view of what an implementation of Vocalizer looks like.7

A close-up view of what an implementation of Vocalizer looks like (Large preview8)

The benefit of using NameShouts’ API is that it makes the implementation as quick as possible. In its simplest usage, there are only two steps required to add it to a website.

First, you must include the Javascript library before the closing </body> tag within the code of your website:

<script type="text/javascript" src="">

Next, all you have to do is wrap your first name in a <span> tag with the specified attributes:

<span class="vocalizer" data-source="auto">NAME</span>

Note: The latest version of Vocalizer.js is available on CDNJS9, or you can choose to download10 and serve the files from your own server.

As you might have noticed, the data-source attribute is set to auto in the example above. This attribute determines the source of the audio file.

When data-source is set to auto, the library will use the NameShouts API. This option is completely hands-off. Vocalizer will automatically search NameShouts’ name listing and feed in the audio file from their servers.

The alternative option is to manually record and use your own audio file instead of the API. In this scenario, the data-source attribute should be set to the path to your audio file. For example:

<span class="vocalizer" data-source="assets/audio/daenerys.mp3">Daenerys</span>

There’s a chance that NameShouts’ library does not have the pronunciation for your name, and in that event, you should use your own audio recording or Vocalizer won’t be doing its job!

How It Works Link

The actual source code for Vocalizer.js is about eighty lines of code. Let me explain exactly what’s happening under the hood.

When the user wraps his or her name within the <span> tag with the class vocalizer, a Javascript function stores that name into a string:

var name = document.getElementsByClassName('vocalizer');
var names = [];

for (var i = 0; i < name.length; i++) {
  var data_source = name[i].getAttribute("data-source");
  names[i] = name[i].innerHTML.toLowerCase().replace(/\W/g,'')
  var request = buildRequests(names[i]);
  fetchAudio(data_source, request, i);

We perform this inside of a loop in case there are multiple usages of Vocalizer on the page.

Next, a conditional checks the data-source attribute to see if you’re opting to use the NameShouts API to source the pronunciation or if you’re using your own audio file:

var data_source = name[i].getAttribute("data-source");

if (data_source == 'auto') {
  /* code for using NameShouts API */
else {
  /* code for using your own audio file */

The buildRequest() function that we call inside that loop returns the path for the endpoint based on the user’s name.

function buildRequests(n) {
  return request = ''+n;

From there, we pass the request to the fetchAudio() function and make our xmlHttpRequest to the NameShouts API.

var xhr = new XMLHttpRequest();'GET', request, true);
xhr.onload = function (e) {
  if (xhr.readyState === 4) {
      if (xhr.status === 200) {
        var audioPath = JSON.parse(xhr.responseText).message[names[i]][0]["path"];
        var audio = new Audio(BASE_URL+audioPath+'.mp3');
        audio.playbackRate = 0.75;
        name[i].addEventListener('click', function() {
        }, false);
      } else {
xhr.onerror = function (e) {

NameShouts’ API returns a JSON object that contains the name of the audio file corresponding to your name. From there, we combine NameShouts’ base URL (where the audio files are stored) and the audio file’s path.

In the event the name you are targeting does not exist within the NameShouts API, the plugin will throw an error.

A solution to this situation would be to record and link your own audio file. Setting the data-source attribute to a file path designates your own audio file. In that case, we just create an Audio element based on the file path from data-source:

var audioPath = sourceType;
var btn = document.getElementsByClassName('vocalizer');

var audio = new Audio(audioPath, function() {

On the front end, an audio button appears after the targeted name. The cosmetics are added with CSS styles on the pseudo-element :after on the <span> tag.

Finally, we add a click event to the audio button:

btn[i].addEventListener('click', function() {;
}, false);

Other Use Cases Link

Example: Blogs and News Publications Link

Vocalizer’s use case can extend beyond just personal websites. I can see blogs and digital news publications begin to adopt the plugin, as well.

An example of how Vocalizer could be used by news publications, such as

An example of how Vocalizer could be used by news publications, such as (Image credit12) (Large preview13)

Imagine you are browsing news stories on Vox.com14 and you see the name of a political figure or a region of the world with a name in which you are unfamiliar. In that situation, Vocalizer could educate you on its pronunciation. In theory, this would better equip you to discuss these current events and issues. No one wants to sound uninformed.

Example: Social Media Platforms Link

Another hypothetical use case could be on social media websites. LinkedIn comes to mind for its role in facilitating professional connections.

Potential usage on social media websites, such as LinkedIn.15

Potential usage on social media websites, such as LinkedIn (Image credit: LinkedIn16) (Large preview17)

In an age when people often connect with each other via social media platforms, such as Facebook, Twitter, or LinkedIn, prior to meeting — a tool like Vocalizer could prove useful.

Unbeknownst to me, Facebook recently rolled out a similar feature that automatically generates audio to enunciate names.

Facebook's feature that displays the pronunciation of names18

Facebook’s feature that displays the pronunciation of names (Image credit19) (Large preview20)

It’s nice to see mainstream platforms focus on these types of accessibility features. Unfortunately, there is no guarantee that autogenerated playback will be correct. Facebook’s pronunciation tool mangles my last name.

Challenges Link

With every potential solution, there are problems. Vocalizer faces issues of its own. The main issue is that two people with the same name do not always pronounce their name in the same way.

Often, a person’s origin language dictates the pronunciation of their name. For example, the name José in Spanish is pronounced HOH-SEH. In French, the same name is pronounced JOO-ZE. Vocalizer’s current implementation does not cater to these circumstances unless you opt to use a custom recording.

Pushing Accessibility Further Link

In the last few years, web evangelists have emphasized the importance of web accessibility. Most accessibility functions cater to people with physical and cognitive disabilities. I believe there is a lack of attention in regards to inclusion and cross-cultural accessibility.

Though unintentional, in a way, Vocalizer seeks to enable cultural accessibility. Technology companies continually strive to diversify their workforces. We’re seeing heightened mobility in our professional lives. As a result, multiculturalism is becoming more and more prevalent.

For what it is — I hope Vocalizer helps familiarize people with names from other cultures or ethnicities.

The Future Of Vocalizer Link

There are a few features and improvements I would like to make on future versions of Vocalizer.js:

  • Language support for names with alternate pronunciations
  • More graceful handling of implementation errors
  • Adding a fallback for the situations when a name is not in NameShouts’ API
  • Ability to easily customize audio buttons styles

To further expand on the idea, I launched a free, web-based version of Vocalizer at

The web tool allows you to record your name in the browser. Then, it generates the code snippet required to add Vocalizer to your website.

Conclusion Link

A 2014 study22 found that people with easier-to-pronounce names are deemed “more trustworthy”. I built Vocalizer to solve a problem that has persisted all my life. Now, I hope this will prove useful to others, helping them solve the same problem.

Thanks so much for reading! Please don’t hesitate to tweet to me23 if you have any questions, comments or feedback.

(vf, aa, il)

Footnotes Link

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23

↑ Back to top Tweet itShare on Facebook

Atif Azam is a software designer and developer based in New York City. These days, he is interested in design systems and how design and technology can be used to enable authentic human interaction. He is a product designer at MongoDB, Inc.

  1. 1

    That’s awesome, great work on building a great approach to solve a very common problem – pronunciation of unorthodox names/words.

    I’ve been thinking about another approach that might accomplish something similar, without relying on recordings. The approach would require writing an IPA (International Phonetic Alphabet) transcription next to the word like so:
    Atif /ˌa:tɪf/
    It’s not something unusual or groundbreaking, Wikipedia already uses it for lots of names:

    Then, if we find an open-source Text To Speech module that can read IPA it’ll be easy enough to make a browser extension that can read the pronunciation transcription next to the name (by adding an icon like yours or by just clicking on the transcription).

    Sadly, the closest thing that I found that used to work in the past is just this:

    If anyone finds a working IPA TTS module please post it below, we may make names more accessible on the web someday.

    • 2

      Wikimedia does have an open ticket for automated IPA to sound, but the challenge at scale appears to be quality control as IPA markup does not map directly to pronunciation.

      There has been success in getting eSpeak to work in the browser as JavaScript through Emscripten and processing IPA using lexconvert‘s correspondences does appear to yield reasonable results: (eSpeak, unfortunately does not, does not handle IPA directly.)

  2. 3

    Thanks, Alex :)

    The approach you mention could definitely work! I believe that’s similar to how Facebook approaches the problem on their profile pages. They generate the audio pronunciation based on the enunciation you select.

  3. 4

    I absolutely love this!

    I have a pretty normal American name – Timothy – but I was born and raised in Japan ( I am a navy brat ).

    I am pretty sensitive to people’s frustration with how their name is pronounced – and understand its not anyone’s fault for getting it wrong. That being said, being able to hear the correct pronunciation before meeting someone, especially in a professional setting, its fantastic! Plus, how good of an impression would you make when you say someones name, that usually goes mispronounced, correct on the first try?!

  4. 5

    Laura Kajpust

    January 1, 2017 5:51 pm

    This is great! People pronounce my last name wrong when we first meet all the time. Definitely going to implement this on my site. Thanks! (I also had no idea Facebook had name pronunciation — checked it out, and it actually got my last name right! Ha! Go figure.)

    • 6

      Thanks, Laura! Awesome to hear that you’ll get some use out of it. Let me know if you have any feedback :)

  5. 7

    Just a comment. What a great, easy approach in teaching people with technology. Most people are open to being taught in this non-intrusive way. And it is awesome that you took the time to lay out the code making it transparent what your intentions are (although this website is mostly used by developers). I hope you can get all the kinks worked out and I can’t wait to see examples of your tool out in the wild.

  6. 8

    Good idea,
    I would suggest to make “span” + “vocalizer” class just defaults and enable users to provide their own CSS selector during initialization.
    You are probably aware how GA configuration is set on window object and than picked by async loaded script later – something like that.

    And probably providing sources on github would be nice so we can have npm package to bundle.
    I am personally not going to audit that minified js file you provided to check if it is not doing anything malicious => not planning to use it ever if source could not be audited or it will not be provided by well known companies like FB or Google.

    Good luck

  7. 9

    While it’s not necessarily fully available, the Web Speech API could be leveraged by providing a SSML formatted version of the IPA standard to enable proper text-to-speech pronunciation. Love the idea.


↑ Back to top