MailtoUI

v   13 KB

A simple way to enhance your mailto links with a convenient user interface.

This mailto link
is using MailtoUI
arrow up
                                
                                    <a class="mailtoui" href="mailto:mario@teclaworks.com">Try it now</a>
                                
                            

What is MailtoUI?

MailtoUI is an open source JavaScript library that enhances your mailto links with a convenient user interface. It gives your users the flexibility to compose a new message using a browser-based email client or their default local email app. MailtoUI is written in vanilla JavaScript, so it's nice and lean with no dependencies to worry about. It works across virtually all devices and modern browsers for desktop and mobile.

MailtoUI is ideal for static sites or any other site where you don't want to spend time setting up a "Contact Us" form solution. Simply drop the MailtoUI script into any page where you want to use it, enable your links, and your users will have a better, more flexible experience interacting with the mailto links on your site.

Motivation

We've all done it at some point. You visit a site, you want to contact someone. You click on the mailto link, only to open the default local email app, which you (most likely) don't use. You then have to close the email app. Go back to the site, copy the email address, go to your browser-based email client, compose a new email, and finally paste in the email address... There's got to be a better way!

Setup

CDN

The easiest way to load MailtoUI is to pull it into your page via CDN. Add it to the bottom of your page, just before the closing </body> tag.

                                
                                    <body>
                                        ...
                                        ...
                                        <script src="https://cdn.jsdelivr.net/npm/mailtoui@latest/dist/mailtoui-min.js"></script>
                                    </body>
                                
                            

DOWNLOAD

Alternatively, you can download mailtoui-min.js and load it at the bottom of your page, just before the closing </body> tag.

                                
                                    <body>
                                        ...
                                        ...
                                        <script src="your/path/to/mailtoui-min.js"></script>
                                    </body>
                                
                            

Loading MailtoUI at the top

If you want to load MailtoUI at the top of your page, you must add the defer or async=false attribute to the script tag. Either one will defer execution of MailtoUI until after the page has been parsed.

                                
                                    <head>
                                        ...
                                        ...
                                        <script src="your/path/to/mailtoui.js" defer></script>

                                        <!-- OR -->

                                        <script src="your/path/to/mailtoui.js" async=false></script>
                                    </head>
                                    <body>
                                
                            

NPM

MailtoUI is also available on npm and can be installed using npm or yarn.

                                
                                    # install the latest version using npm
                                    npm i mailtoui

                                    # install the latest version using yarn
                                    yarn add mailtoui
                                
                            

Usage

After adding the MailtoUI script to your page, all you need to do is attach the mailto links on the page to MailtoUI. You do that by making sure each mailto link has the class mailtoui.

The default class is mailtoui. In the unlikely event that this class collides with your own CSS code, there's an easy way to change it, which is explained in the Options section.

                            
                                <a class="mailtoui" href="mailto:tony.stark@example.com">Tony</a>

                                <a class="mailtoui" href="mailto:pepper.potts@example.com">Pepper</a>
                            
                        

That's it. That's the most basic setup. Your mailto links are now ready to use MailtoUI. For more functionality, please read on!

URI Scheme

MailtoUI supports the most commonly used mailto header fields (mailto URI scheme) that let you specify other details in addition to the email address. This means MailtoUI is compatible with the mailto links you may already have on your page with any of these parameters:

  • subject
  • cc*
  • bcc*
  • body

These header fields must comply with the mailto URI scheme encoding requirements, as specified in RFC 6068. For more information about mailto links, checkout MDN's E-mail links.

* Sadly, Outlook does not currently support the cc and bcc fields in mailto links.

For live examples with these parameters, check out the Examples section.

Options

Options can be set via a data-options attribute in the script tag. Options must be specified as a JSON formatted string. The following options are supported:

OPTION DEFAULT DESCRIPTION
autoClose true

When set to true, the MailtoUI interface is closed automatically when any of the email client choices is clicked. autoClose has no effect when clicking on the Copy button.

linkClass mailtoui

The class used on mailto links attached to MailtoUI.

autoClose

If you set autoClose to false, the MailtoUI interface will remain open after clicking on any of the email client choices.

                            
                                <body>
                                    ...
                                    ...
                                    <script src="mailtoui.js" data-options='{ "autoClose": false }'></script>
                                </body>
                            
                        

linkClass

Use the linkClass option to change the class used to attach mailto links to MailtoUI. This can be handy in the unlikely event that the default mailtoui class collides with your own CSS code.

                            
                                <body>
                                    <a class="superhero" href="mailto:thor@example.com">Thor</a>
                                    ...
                                    ...
                                    <script src="mailtoui.js" data-options='{ "linkClass": "superhero" }'></script>
                                </body>
                            
                        

If you set a custom link class, be sure to use the same class on your mailto link(s). For example, if you set the linkClass option to superhero, your mailto link(s) must contain the class superhero, as shown above.

Custom Styling

You can easily change the look of MailtoUI to match your site's branding. Simply update a few MailtoUI classes in your own CSS. Here's an example of a dark themed interface.

Try it yourself!

                            
                                /* Dark theme */

                                .mailtoui-modal {
                                    background-color: rgba(250,250,250,0.5);
                                    color: #fff;
                                }

                                .mailtoui-modal-head {
                                    background-color: #21262C;
                                }

                                .mailtoui-modal-title {
                                    color: #fff;
                                }

                                .mailtoui-modal-close:hover {
                                    color: #fff;
                                }

                                .mailtoui-modal-body {
                                    background-color: #373b41;
                                }

                                .mailtoui-client:focus .mailtoui-label {
                                    background-color: #D8DCDF;
                                    color: #333;
                                }

                                .mailtoui-label,
                                .mailtoui-copy-button {
                                    background-color: #63676b;
                                    color: #fff;
                                }

                                .mailtoui-label:hover,
                                .mailtoui-label:focus,
                                .mailtoui-copy-button:hover,
                                .mailtoui-copy-button:focus {
                                    background-color: #D8DCDF;
                                    color: #333;
                                }

                                .mailtoui-copy-email-address {
                                    background-color: #909295;
                                    color: #21262c;
                                }

                                /* End dark theme */
                            
                        

The link class is used as a prefix in the default MailtoUI CSS. If you set a custom link class via the linkClass option, then you must use that as the prefix in your overriding CSS. For example, if linkClass is set to superhero, then all the classes in the code above should begin with .superhero- instead of .mailtoui-.

Accessibility & Responsiveness

MailtoUI is built with accessibility and responsiveness in mind. Much care has been put into adding these small but important features, to make sure it's accessible and it renders properly in virtually all screen sizes:

  • Alert screen readers of the modal's presence when shown
  • Alert screen readers of the modal's absence when closed
  • Modal can be closed by using the Esc key
  • Modal can be closed by clicking on the overlay
  • User can only tab within the modal when shown
  • Hight contrast colors used in the default styling
  • Modal's size auto-adjusts based on screen size
  • Modal is scrollable if screen size forces its content out of view
  • When modal is closed, focus returns to the last focused element on the page

Examples

Here are a few working examples of mailto links attached to MailtoUI.

With subject

                            
                                <a class="mailtoui" href="mailto:user1@example.com?subject=Hi%20there!">With subject</a>
                            
                        

With cc

                            
                                <a class="mailtoui" href="mailto:user2@example.com?cc=user3@example.com">With cc</a>
                            
                        

With multiple bcc - You can do the same with cc.

                            
                                <a class="mailtoui" href="mailto:user3@example.com?bcc=user1@example.com,user5@example.com">With multiple bcc</a>
                            
                        

With body

                            
                                <a class="mailtoui" href="mailto:user4@example.com?body=Hope%20you're%20doing%20well.">With body</a>
                            
                        

With all fields

                            
                                <a class="mailtoui" href="mailto:user5@example.com,user2@example.com?subject=Winter%20is%20coming&cc=user3@example.com,user4@example.com&bcc=user1@example.com&body=Fear%20cuts%20deeper%20than%20swords.">With all fields</a>
                            
                        

With no fields - yes, it's a valid mailto link 😉

                            
                                <a class="mailtoui" href="mailto:">With no fields</a>
                            
                        

A PROJECT BY

Unmodified icons by Font Awesome