How to Make a Custom Keyboard for Mac OS

A guide to using Ukelele

Image for post
Image for post
Standard keyboard layout

In this article you’ll create a custom keyboard layout for Mac OS that you can use to enter special Unicode characters or unsupported languages.

Default keyboards

Mac OS offers a lot of language options and keyboard layouts out of the box. You can find them by going to System Preferences > Keyboard > Input Sources. Then click the + plus button to add another one.

Image for post
Image for post

However, if you speak a minority language or need some other special purpose keyboard, you may not be able to find it.

As a case in point, I’m teaching an English phonetics class this term, and while online keyboards like ipa.typeit.org work fine, I need a more convenient solution to type the International Phonetic Alphabet (IPA) directly on my computer. I also need another keyboard to write traditional Mongolian script, which isn’t included in the Mac OS supported keyboard list.

Creating a custom keyboard

In order to create a custom keyboard, you need to make a keyboard layout bundle. Ukelele will help you do that. It’s a program created by the well known linguistics organization SIL International.

Follow along with me as I make my IPA keyboard. You can adjust the steps to meet your own needs.

Your keyboard will be inputting Unicode characters, so first of all you should gather the characters that you’ll need. Here are some places that you can do that:

For me, ipa.typeit.org has most of the special characters that I need:

Download Ukelele from the official site and install it.

When you open it the first time it should look something like this:

Image for post
Image for post
Blank Ukelele keyboard design layout

This article will teach you to make a new keyboard layout completely from scratch. Although opening an existing keyboard and editing it may be a faster way to get a finished product, it can be more complicated to understand when making a keyboard layout for the first time.

In the menu choose File > New Keyboard Layout.

You’ll get a popup asking you to name your layout. Since I’m making an IPA keyboard I’ll name mine IPA. I want to start from scratch, so I’m choosing Empty as the base keyboard layout. I want Command shortcuts like Cmd+C to still work, so I’ll choose QWERTY for the layout with the command key.

Image for post
Image for post

Press OK to create your layout.

Then in the menu choose File > Save and save it as ipa.keylayout in a location of your choice. You’re saving it now to ensure you don’t loose your work later.

Note: You can also save as a Bundle, but this isn’t necessary unless you want to do more advanced things like add an icon. For this first keyboard layout we’ll just use the basic .keylayout extension, which is an XML file.

You can close the original Ukelele window that was showing when you first opened the program. Just keep open the IPA keyboard layout that you just created.

The way to enter a value for a key is to double-click it.

Start by double-clicking what would be the a key on most keyboards and then pasting in the IPA ɑ value that I collected earlier:

Image for post
Image for post

Press the Done button to save your change. Your key should now look like the following:

Image for post
Image for post

You may notice that single-clicking a key or pressing a key on your keyboard highlights the key in Ukelele. That doesn’t matter. You can click or press the key again to deselect it. Pressing Shift or Command or one of the other modifier keys will turn it green. You’ll be doing that later.

If you want to enter a character by its Unicode value rather than pasting it in, you can do that by entering the value in XML format. For example, the Unicode hex value of ɑ is 0251. To put that in XML format you would write it like so:

That is, prefix the value with &#x and end it with ;. (If you’re using decimal rather than hexadecimal, then leave off the x.) Here is what it looks like entering the hexadecimal value:

Image for post
Image for post

Double-click all of the empty keys on the keyboard to give them a value. I’m using the following values:

Note: Don’t forget to add a space to the space bar key!

Save your work with File > Save. The layout looks like this now:

Image for post
Image for post

I don’t really care about the keypad on the right but if you wanted to be complete you could fill it with values like this:

Image for post
Image for post

There are still more Unicode values that I want to add but the keyboard is already full. The primary way to add more values is to use the modifier keys. These include Shift, Option, Command, Control, and Caps Lock. Use Shift and Option as your first choice since Command may be used for various shortcuts on your computer.

For the IPA keyboard I’m making, I’ll be able to get all the characters I need just using Shift. However, you could use Option or Shift+Option to get even more ways to enter characters if you need that many.

Press Shift now. You’ll notice that the Shift buttons on your Ukelele layout turn green and that all of your other key values disappear:

Image for post
Image for post

With the Shift key held down, double-click an empty key to add a value to it. I’ll add the character æ to what would be a capital A on a normal English QWERTY keyboard.

Image for post
Image for post

When the keyboard layout is finished, this will allow me to enter æ by pressing the Shift key in combination with that key.

Holding down Shift and double-clicking empty keys, add all the remaining characters you need.

There are the characters I still need to add:

After filling those in, the keyboard with the Shift modifier looks like this:

Image for post
Image for post

There are a number of blank keys that don’t have anything, but that’s OK with me since they are just Shift modifier keys.

Save your work again with File > Save.

Install the keyboard

There are a few steps you need to do to install the keyboard.

In Ukelele go to File > Install > Show Organizer. You should see your keyboard in the left column.

Image for post
Image for post

Right-click the ipa keyboard item and choose Install for Current User:

Image for post
Image for post

You’ll get the following warning. Choose Close.

Image for post
Image for post

As the warning says, you shouldn’t edit the file after you’ve installed it. Installing for the current user moved ipa.keylayout to the hidden folder Library/Keyboard Layouts in your home directory. You can view hidden folders and files in Finder by pressing Command+Shift+..

As Ukelele recommends, log out of your current Mac user session and then log back in again. Alternatively, restart your computer.

Like you saw at the beginning of this article, go to System Preferences > Keyboard > Input Sources. Then click the + plus button to add another one.

Image for post
Image for post

Scroll down and choose Others from the list on the left. Then choose the IPA keyboard on the right. Finally, press the Add button.

Image for post
Image for post

Note: If you want to associate your keyboard with a specific language, then you need to create a collection bundle rather than a single keylayout file.

As long as you have the input source showing in your toolbar, you can switch keyboard layouts by selecting the icon. Choose IPA from the list:

Image for post
Image for post

naʊ ju kæn raɪt wɪθ jɝ nu kibɔrd!

Updating your layout

You will probably discover that you want to make a few changes after you’ve finished your keyboard. For example, in that last line of the section above I had to switch keyboards in order to enter the !. It would be nice to add a little punctuation back into that keyboard.

Open Ukelele and go to View > Show Organizer.

Then right-click ipa and choose Uninstall or just drag it to the Not Installed column.

Image for post
Image for post

Since the layout is uninstalled now, it’s safe to edit. You can open the file by going to File > Open Recent and choosing ipa.keylayout.

Make your changes and then save the file.

In Ukelele go to View > Show Organizer again drag ipa back to the Installed for Current User column.

Image for post
Image for post

Select Close when prompted.

Log out of your Mac user and then log back in again. The changes should have taken effect. If not, try restarting your computer.

Going on

You can learn a lot more by reading the documentation. In Ukelele go to Help > Ukelele Manual (PDF). Also check out the tutorials in the Documentation folder in the dmg image that you got when you downloaded Ukelele.

In this article you created a layout from scratch, but an easier way would be to start with a similar layout and just edit that. An easy way to do that is to go to File > New from Current Input Source. There are also a lot of layouts in the Resources folder that came with the Ukelele download. See the documentation for instructions.

In addition to modifier keys, you can also set up dead keys to give you even more options for input. You can make almost any key a dead key. A dead key is like a modifier key but when you press it, nothing happens until you press another key. For example you could make the ` key add an accent to whatever key comes next.

Anyone can use your layout if they just copy it to the Library/Keyboard Layouts folder of their home folder. For less technical users, Ukelele can also make a dmg file that will help people install the layout.

A Flutter and Dart developer. Follow me on Twitter @suragch1 to get updates of new articles.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store