Hyperlink

Hyperlink is a Statamic addon that expands the default Link fieldtype and allows you to store link text and target options alongside the link destination.

Hyperlink is great for CTAs, callouts, and hero buttons, and has everything you need for a smooth author and developer experience:

• Link to everything including entries, URLs, email addresses, assets, taxonomy terms, and phone numbers
• Multi-site support for localizing links
• Flexible templating options for both Antlers and Blade
• Reusable field configurations across blueprints using Profiles

Get Started

• Installation
• Configuration
  • Profiles
  • Profile options
  • Field-specific settings
• Templating
  • Antlers
  • Blade
  • Available data
• Validation
• Schema
• Licensing

Installation

You can find and install Hyperlink from the Statamic control panel under Tools → Addons, or install from your project root using Composer.

composer require bencarr/statamic-hyperlink

Configuration

Add a Hyperlink field to your blueprint by selecting it from the “Relationship” or “Special” groups.

Profiles

Profiles let you re-use Hyperlink configurations across multiple blueprints. You can set up profiles in a config file, then select which profile each field should use. Future changes can be made in the profile configuration without needing to update each field’s settings.

Customizing the default profile

Start customizing profiles by publishing the hyperlink-config tag.

php artisan vendor:publish --tag=hyperlink-config

You can find the published configuration in config/statamic/hyperlink.php.

Adding additional profiles

Make additional profiles available by adding new keys to the profiles array.

<?php
return [
    'profiles' => [
        'default' => [
            // ...
        ],
        'hero' => [
            // ...        
        ],
    ],
];

Profile options

Each profile can be customized using the following options.

Pro Tip — You can also re-order the link type dropdown by adjusting the order of the types array in your profile. For example, to make the “Asset” option appear first, set the types property to ['asset', 'entry', 'url', 'email', 'term', 'tel'].

Field-specific settings

To bypass profiles and use a one-off configuration for a particular field, select the “Custom” profile in the field settings pane, which surfaces the same profile configuration options in the UI and saves the settings to the blueprint itself.

FYI — When using the “Custom” profile, enabled link types cannot be reordered.

Templating

Hyperlink works great with both Antlers and Blade, and has built-in conveniences to give you full control over your template markup.

Antlers

In your Antlers templates, reference the field value like any other field to return a plain hyperlink with all the necessary info.

{{ entry.hyperlink }}

<!-- Output -->
<a href="https://statamic.com">Rad Button Text</a>

Note — The target attribute will be added automatically when the “New window?” toggle is checked.

For maximum flexibility, you can access any of the available data from the Hyperlink field:

<a href="{{ entry.hyperlink.url }}" target="{{ entry.hyperlink.target }}" class="button">
    {{ svg src="" }}
    {{ entry.hyperlink.text }}
</a>

Blade

In your Blade templates, reference the field value like any other field to return a plain hyperlink with all the necessary info.

{{ $entry->hyperlink }}

<!-- Output -->
<a href="https://statamic.com">Rad Button Text</a>

Note — The target attribute will be added automatically when the “New window?” toggle is checked.

For simple markup modifications like adding a class or an attribute, you can chain class and attributes methods similar to Blade component attributes:

{{ $entry->hyperlink->class('button')->attributes(['x-on:click' => 'doSomething' ]) }}

<!-- Output -->
<a href="https://statamic.com" class="button" x-on:click="doSomething">Rad Button Text</a>

For maximum flexibility, you can access any of the available data from the Hyperlink field:

<a href="{{ $entry->hyperlink->url }}" target="{{ $entry->hyperlink->target }}" class="button">
    @svg($entry->hyperlink-type)
    {{ $entry->hyperlink->text }}
</a>

Available data

The field value of a Hyperlink field is a HyperlinkData object, which works just like an array in your templates. Inside you’ve got access to everything you’ll need to completely customize your presentation:

Note — When linking to a Term, Hyperlink will generate a URL to the global term view. If you’d like to link to the term in a specific collection, you’ll need to use the term property to generate that collection-specific URL in your templates.

Validation

In general, Hyperlink fields require both the link value and link text. If the Hyperlink field is optional in the Blueprint, a “None” option is added to the available link types for authors to explicitly leave the field blank (and it’s the default for new entries).

Type-Specific Validation

Some link types are also validated conditionally: - URL — Uses Laravel’s url validation rule unless the value begins with #, ., or / (so anchors like #contact and relative paths like ./sub-page work just fine) - Email — Uses Laravel’s email validation rule - Phone — Uses Laravel’s regex validation rule with the broad pattern /[\d,.+\-()]/, which aims to prevent big errors, but accommodate the variety of formats allowed in tel: links

Schema

Hyperlink data is stored as a simple YAML structure:

---
title: My Entry
hyperlink:
  type: url
  link: 'https://statamic.com'
  text: 'Rad Button Text'
  newWindow: false
---

Entry, Asset, and Term links are stored using an ID reference, so links stay up-to-date event if the related item’s URL changes:

---
title: My Entry
hyperlink:
  type: entry
  link: 'entry::AAA111B2-3333-4444-C555-D6E7FGH8I910'
  text: 'Rad Entry Link'
  newWindow: false
---

Licensing

Hyperlink is a Commercial Addon.

You can use it for free while in development, but requires a license to use on a live site. Learn more or buy a license on The Statamic Marketplace!