Practical guide · Vanilla JavaScript

How to replace a mailto link with a webmail picker

Install one package, initialize it once, then keep using normal mailto links. Visitors get a webmail picker when smart-mailto is available and the original link when it isn't.

Try the upgraded link Jump to the code

npm package ↗GitHub repository ↗

Step 1

Install the core package

The core package is framework-agnostic and has no runtime dependencies.

Terminal

npm install @smart-mailto/core

Step 2

Initialize smart-mailto once

Put the import and initializer in your browser entry file. One capture-phase listener handles current and future mailto links on the page.

main.js

import { initSmartMailto } from '@smart-mailto/core';
initSmartMailto();

Two common options

theme: Use 'light' or 'dark' to match a fixed site theme. The default, 'auto', follows the visitor's system preference.
preferredProvider: Pass a provider ID such as 'gmail' to place it first. This takes priority over the browser-based regional order.

Step 3

Add or keep a normal mailto link

smart-mailto listens for valid mailto anchors across the document. You don't need a custom component, and existing subject and body fields stay intact.

Your HTML

<a href="mailto:hello@example.com">
  Email us
</a>

That's the full migration.

You can keep adding normal mailto anchors. The same initializer handles them.

What visitors get

A picker that adapts without an IP lookup

A valid mailto click opens the provider picker with the recipient, subject, and body preserved. Provider order can reflect the recipient's email domain, a saved choice, and regional signals from the browser's timezone and language. Geo detection makes no network request.

When native mail already works

The picker adds a step for visitors whose existing mail handler already works. Native mail is included by default on mobile. Desktop sites can offer the same option with includeNative: true.

Later clicks on this site open the remembered provider directly. Set skipPickerOnRememberedChoice: false to keep the picker, or add data-smart-mailto-force-picker to a change-app link.

Gmail

Outlook

Proton Mail

Yahoo Mail

Fallback behavior

The original link remains the safety net

JavaScript is unavailable

The browser still sees the original mailto anchor and can open its configured mail app.

The picker cannot load

smart-mailto redirects back to the original mailto URL so native behavior can continue.

The recipient is empty or invalid

smart-mailto does not intercept the click. The browser handles the link normally.

Compare approachessmart-mailto vs. plain mailto →Troubleshoot firstWhen a mailto link opens nothing →

Ready to ship

Three steps, one dependable mailto fallback.

Install from npm, browse the source on GitHub, or open the full configuration reference.

Tried the guide? Share your first stopping point ↗