Link Purpose Icons

The Link Purpose JS library attaches icons and screen reader hints to links that open external sites, open new windows, send emails, download documents, make calls and open third-party apps.

Accessibility guidelines encourage giving users advance warning if clicking a link causes this type of change of context.

The library includes a default set of icons:

If you want to bring your own icons, the module config page has settings for CSS class-based icon libraries (e.g. Font Awesome Icons). Icons that involve changing the HTML, such as inline SVG and Material Icons, can be implemented using custom JS in your theme; reference "Community Documentation" below.
 

Features

1. Icons automatically match link color, even when modified on :hover or :focus, or by system high contrast settings.
2. The last word of each link is wrapped into a span with the icon, preventing line breaks between the text and the icon.
3. Links can be excluded by page region or any CSS selector.
4. Icons and the visually-hidden text for screen readers are in separate containers, allowing designers to remove the icon or the text if context makes one or the other redundant.
5. For multilingual sites, the visually-hidden text for screen readers passes through Drupal's translation system.
6. Dynamically inserted (AJAX) links, as well as links inside Shadow DOM / Web Components can be marked as well.

The library accepts numerous parameters for its markup. By default, it will convert this:

<a href="https://example.com">
    EXAMPLE LINK
</a>

to this:

<a href="https://example.com" class="link-purpose link-purpose-external" aria-describedby="link-purpose-description-1">
    EXAMPLE
    <span class="link-purpose-spacer"> </span> 
    <span class="link-purpose-nobreak link-purpose-last-word">
        LINK
        <span class="link-purpose-icon link-purpose-external-icon" aria-hidden="true" title="Link is external">
            <svg ...></svg>
        </span>
        <span class="link-purpose-text" id="link-purpose-description-1">
             Link is external
         </span>
    </span>
</a>

Much of that is helper classes for themers:

• The link itself receives identifying classes, as well as an aria-describedby connection to descriptive text.
• A spacer is added before the last word, so it can be sized or hidden.
• The last word is wrapped in a span with the icon, to allow for fine control of text/icon wrapping.
• The icon wrapper has its own classes, and a title tag for mouseovers.
• The descriptive text for screen readers is visually hidden by default, but can be separately targeted by CSS as needed.

Post-Installation

It should work out of the box with no configuration overrides at all.

Optionally: set domains you want considered internal in absolute URLs on the configuration page. By default the site's base URL will be used.

Additional Requirements

None. It's vanilla JS.

Recommended modules/libraries

Editoria11y Accessibility Checker.

Similar projects

The External Links module can also mark email and external links. Key differences:

• The Link Purpose module adds five additional categories (document, telephone, file download, app and new window), allows themes to insert custom link categories, adds line break prevention, and has no jQuery dependency.
• The External Links module can create "You are leaving the site" popup windows on external links.

The Link Purpose configuration page has instructions for settings that will emulate External Links' markup to assist with migration.

Supporting this Module

Help testing right-to-left languages would be appreciated.

Community Documentation

The Link Purpose JS library docs detail additional settings that can be injected by themes or modules -- e.g., adding additional categories of links or using HTML based icon libraries.

To use these parameters:

1. Check the box on the configuration page "Attach library then stop; theme will mark links."
2. Create a duplicate of the module JS that sends parameters to the library.
3. Customize the parameters coming from drupalSettings or add your own.

Project meta