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 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!
Hey @mariordev! https://t.co/8B3bkh65Tk is awesome. Whenever I click the contact link on a website, and it opens the Mac Mail app instead of going to a contact page, I get a little bit furious, so I appreciate what you’re doing here
— Stuart of Vacord (@vacord) January 10, 2019
This is so needed pic.twitter.com/Pc4QB3MkJq
— Kelly Miller (@KellyFMill) January 9, 2019
This is super nice, thanks for building it 🙂
— Hugo Di Francesco (@hugo__df) January 9, 2019
If you hate those 'mailto' links which always try to open your default email app, I highly recommend you to check out #mailtoUI by @mariordev!!!
— Krishan 🤖 (@NaorayKroaths) January 9, 2019
Super easy to set up and customize 🔥https://t.co/d62y7KjQyh
Installation
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@{{ version }}/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-min.js" defer></script>
<!-- OR -->
<script src="your/path/to/mailtoui-min.js" async=false></script>
</head>
<body>
NPM
MailtoUI is also available on npm and can be installed using npm or yarn.
# install using npm
npm i mailtoui@{{ version }}
# or using yarn
yarn add mailtoui@{{ version }}
Usage
After adding MailtoUI to your page via the <script> tag, all you need to do is attach the mailto links on the page to MailtoUI. You do that by simply adding the mailtoui class to each mailto link.
<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. Your mailto links are now ready to use MailtoUI. Save your work and reload the page. MailtoUI will run itself automatically on page load, recognizing each mailto link, and rendering the UI whenever a mailto link is clicked.
In the unlikely event that the mailtoui class collides with your own CSS code, there's an easy way to change it, explained in the Options section.
Running MailtoUI manually
Of course, when you install MailtoUI via npm or yarn, it cannot run itself on page load, as it does when you install it via the <script> tag. MailtoUI supports the ES5 require method of loading modules. You need to load MailtoUI into your script and run it manually at the appropriate time, once the DOM is ready. For example, with Vue.js that would be in the mounted() method, as shown below.
HTML
<div id="app">
<a class="mailtoui" :href="mailtoHref">{{ emailSyntax }}</a>
</div>
JAVASCRIPT
const Vue = require('path/to/your/node_modules/vue/dist/vue.js');
const MailtoUI = require('path/to/your/node_modules/mailtoui/dist/mailtoui-min.js');
var app = new Vue({
el: '#app',
data: {
email: 'supergirl@example.com',
},
computed: {
mailtoHref: function() {
return 'mailto:' + this.email;
}
},
mounted() {
MailtoUI.run(); // <--- Run MailtoUI manually
},
});
Try it: {{ email }}
Options
Options allow you to easily change the behavior and the appearance of MailtoUI to fit your needs.
Options can be set via a data-options attribute with a JSON string in the <script> tag, or via a JavaScript object argument passed to the MailtoUI run() method.
The following options are supported:
| OPTION | TYPE | DEFAULT | DESCRIPTION |
|---|---|---|---|
autoClose |
Boolean |
true |
If set to true, the MailtoUI modal is closed automatically when an email client choice is clicked. It has no effect when clicking on the Copy button. |
linkClass |
String |
mailtoui |
The class name used on mailto links attached to MailtoUI. |
title |
String |
Compose new email with |
The title of the modal. |
buttonText1 |
String |
Gmail in browser |
Text displayed on button 1. |
buttonText2 |
String |
Outlook in browser |
Text displayed on button 2. |
buttonText3 |
String |
Yahoo in browser |
Text displayed on button 3. |
buttonText4 |
String |
Default email app |
Text displayed on button 4. |
buttonTextCopy |
String |
Copy |
Text displayed on Copy button. |
buttonTextCopyAction |
String |
Copied! |
Text displayed on Copy button when clicked. |
buttonIcon1 |
String |
[embedded] |
URL to an SVG file for button 1 icon. |
buttonIcon2 |
String |
[embedded] |
URL to an SVG file for button 2 icon. |
buttonIcon3 |
String |
[embedded] |
URL to an SVG file for button 3 icon. |
buttonIcon4 |
String |
[embedded] |
URL to an SVG file for button 4 icon. |
buttonIconCopy |
String |
[embedded] |
URL to an SVG file for Copy button icon. |
disableOnMobile |
Boolean |
true |
If set to true, MailtoUI is disabled on mobile devices, including tablets. |
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-min.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-min.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.
buttonText{#}
The buttonText{#} options accept a string to be used as the text displayed on the button. For example, to change the text displayed on the "Outlook" button, use the buttonText2 option.
<body>
...
...
<script src="mailtoui-min.js" data-options='{ "buttonText2": "Outlook" }'></script>
</body>
buttonIcon{#}
The buttonIcon{#} options accept a URL that points to a valid SVG file to be used as the button icon. For example, if you want to change the icon used on the Copy button, use the option buttonIconCopy.
<body>
...
...
<script src="mailtoui-min.js" data-options='{ "buttonIconCopy": "/path/to/your/other-icon.svg" }'></script>
</body>
The URL can be absolute or relative. An absolute URL must be in your own domain. Attempting to use an SVG file hosted on a different domain will result in an CORS policy violation and will not work. In other words, you must host your own SVG file(s).
Setting options at run time
When running MailtoUI manually, any of the options described above can be set by passing a JavaScript object argument to the MailtoUI run() method.
const MailtoUI = require('path/to/your/node_modules/mailtoui/dist/mailtoui-min.js');
MailtoUI.run({ autoClose: false, linkClass: 'superhero' });
Custom CSS
You can easily change the look of MailtoUI to match your site's branding. Simply update a few MailtoUI classes in your own CSS code. Here's an example of a dark themed interface.
/* 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:focus,
.mailtoui-modal-close:hover {
color: #fff;
}
.mailtoui-modal-body {
background-color: #373b41;
}
.mailtoui-button:focus .mailtoui-button-content {
background-color: #D8DCDF;
color: #333;
}
.mailtoui-button-content,
.mailtoui-button-copy {
background-color: #63676b;
color: #fff;
}
.mailtoui-button-content:hover,
.mailtoui-button-content:focus,
.mailtoui-button-copy:hover,
.mailtoui-button-copy:focus {
background-color: #D8DCDF;
color: #333;
}
.mailtoui-button-copy-clicked,
.mailtoui-button-copy-clicked:hover,
.mailtoui-button-copy-clicked:focus {
background-color: #1F9D55;
color: #fff;
}
.mailtoui-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-.
Events
MailtoUI fires up a few MailtoUI-specific events to make it easier to integrate with your code. These may be used to perform various actions as the user interacts with the interface.
| EVENT | ELEMENT ID | DESCRIPTION |
|---|---|---|
open
|
mailtoui-modal
|
The modal has opened. |
close
|
mailtoui-modal
|
The modal has closed. |
compose
|
mailtoui-button-1
mailtoui-button-2
mailtoui-button-3
mailtoui-button-4
|
An email client choice has been clicked. |
copy
|
mailtoui-email-address
|
The email address has been copied to the clipboard. |
For example, if you want to perform some action when the "Gmail" button is clicked, you can attach an event listener to that button to listen for the compose event. Like so:
var gmail = window.document.getElementById('mailtoui-button-1');
gmail.addEventListener(
'compose',
function(event) {
// do your thing...
},
false
);
If you set a custom class name via the linkClass option, remember to replace mailtoui with your custom class name in the Id passed to getElementById().
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:
subjectcc*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.
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.
<a class="mailtoui" href="mailto:user1@example.com?subject=Hi%20there!">With subject</a>
<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>
<a class="mailtoui" href="mailto:user4@example.com?body=Hope%20you're%20doing%20well.">With body</a>
<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>