Token

There are many different modules that work with Drupal's Token API, but the most important one is the Token module. It provides some enhanced functionality for tokens, such as reusable user interfaces for tokens, some missing tokens for specific modules, and crucially, entity field tokens.

For use of tokens beyond what Drupal core offers, the Token module is highly recommended.

Additional documentation for Token module can be found at the Token module handbook.

Token Tree

The Token Tree widget is a user interface element that provides a tree display of all tokens available on the site. In some cases, it even provides information about the tokens available within a specific context, adding additional token types that are relevant to a given input.

An example screenshot of the Token Tree element. Source: https://www.drupal.org/project/token

The Token Tree allows developers and editors to navigate through the tokens available on the site as a hierarchy.

The Name column indicates the name of the token or token type, and the arrow at the left of the row allows token types or chainable tokens to be expanded.

Clicking a token in the Token column will insert the corresponding token into whatever field the Token Tree element was linked to.

The Token Tree element is displayed on demand via Ajax because it can be very large in size, depending on the amount of tokens available on the site and the level of recursion configured in the element.

Tokens added by Token module

Token module adds an array of new tokens that add new token types and add new functionality to existing token types.

Every content entity and entities with token types

Every content entity gains a token type defined by its machine name. This also applies to entities which have a token type defined.

[<entity-type>:url]

[<entity-type>:language]

[<entity-type>:original]

Date

These tokens can be chained from any value that returns a date.

A new current-date token type is added that relates to the current date and time. This is subject to change due to drupal.org issue #943028.

[date:<format-type>]

Node

These tokens can be chained from any value that returns a node.

[node:type] is removed due to deprecation.

[node:source]

[node:log]

[node:content-type]

[node:content-type:name]

[node:content-type:machine-name]

[node:content-type:description]

[node:content-type:node-count]

[node:content-type:edit-url]

Taxonomy term

These tokens can be chained from any value that returns a taxonomy term.

[term:source]

[term:edit-url]

[term:parents]

[term:root]

Vocabulary

These tokens can be chained from any value that returns a vocabulary.

[vocabulary:machine-name]

[vocabulary:edit-url]

File

These tokens can be chained from any value that returns a file.

[file:basename]

[file:extension]

[file:size-raw]

User

These tokens can be chained from any value that returns a user.

[user:cancel-url]

[user:one-time-login-url]

[user:roles]

Current user

[current-user:ip-address]

Menu link

These tokens can be chained from any value that returns a menu link.

[menu-link:mlid]

[menu-link:title]

[menu-link:url]

[menu-link:parent]

[menu-link:parents]

[menu-link:root]

Language

These tokens can be chained from any value that returns a language.

[language:name]

[language:langcode]

[language:direction]

[language:domain]

[language:prefix]

Current page

[current-page:title]

[current-page:url]

[current-page:page-number]

[current-page:query]

[current-page:interface-language]

[current-page:content-language]

URL

These tokens can be chained from any value that returns a URL.

[url:path]

[url:relative]

[url:absolute]

[url:brief]

[url:unaliased]

[url:args]

Array

These tokens can be chained from any value that returns an array, such as [term:parents] or [menu-link:parents].

[array:first]

[array:last]

[array:count]

[array:reversed]

[array:keys]

[array:join]

[array:value]

Random

[random:number]

[random:hash:?]

Image

Requires Image module to be enabled.

These tokens can be chained from any value that returns an image.

[image_with_image_style:mimetype]

[image_with_image_style:filesize]

[image_with_image_style:height]

[image_with_image_style:width]

[image_with_image_style:uri]

[image_with_image_style:url]

How entity field tokens work

Entity field tokens depend on Field module as well as Token module.

Depending on the token value you are trying to fetch, you might have to chain several values together to get to the value you are trying to reach. For example, you might be dealing with nodes and want to print the URL of an image linked through a Media field. You might start with text formatted like so:

The node's Image URL is: [node:field_image:0:entity:field_media_image:entity:url]

This traverses through the following steps in Drupal's content hierarchy:

• Starts with the Node itself
• Fetches items in field_image
• Fetches the first field item
  • Since field lists are zero-based indexing
• Fetches the Media entity linked from this field item
• Within the Media entity, fetches items in field_media_image
• Fetches the File entity linked from this field item
  • Note how we don't specify the index here. We're implicitly selecting the first, but it's important to know that you can explicitly specify the index.
• Generates the URL for the File entity

So in the end, the text returned matches the URL of the image linked through entity references two levels deep.

The output would look something like:

The node's Image URL is: https://my.website.example.com/sites/default/files/2025-04/example-picture.jpg

This is made possible by Token module including its own implementation of hook_tokens that detects deeply-chained tokens and allows recursive calls to Token::generate to be called.

Validating form fields with tokens

A helpful tool provided by the token module is the token_element_validate() callback that works with #element_validate in Form API. This function can be added to any form field that allows tokens and ensures that only valid tokens are provided.

The validator callback performs a number of checks against text inputs:

• If #min_tokens is specified, expects that the number of tokens present in the text input is equal to or greater than this number.
• If #max_tokens is specified, expects that the number of tokens present in the text input is equal to or less than this number.
• If #token_types is specified, expects that there aren't any tokens present in the text that can't fulfill the specified types. For example, a [user:] token in a context that does not support them should be considered invalid.

If any of these expectations fail, the form element has an error set against it.

Since token_element_validate() uses \Drupal::token()->scan() to find tokens in the text input, all tokens must be formatted correctly.

Example Form API element with token_element_validate():

$form['databasics_message'] = [
  '#type' => 'textarea',
  '#title' => t('Message'),
  '#default_value' => \Drupal::config('databasics.settings')->get('message') ?? '',
  '#element_validate' => ['token_element_validate'],
  '#token_types' => ['user', 'node'],
];

Creating a Custom Token

Out of the box, many tokens exist to solve a variety of common use cases for them. Occasionally you may encounter a requirement where no such token exists to facilitate it. Fortunately, implementing custom tokens in Drupal is pretty straightforward.

From Creating a Custom Token in Drupal 8, see also Drupal 8 how to have custom tokens with html in them properly replaced for tips on how to allow HTML.

Here's an example module based on the excellent article by Kevin Quillen.

In this example, the challenge is that "Author" and "Author location" fields can both be empty or not, in which case the labels should not be printed (See it in use at the bottom):

<?php

declare(strict_types = 1);

use Drupal\Core\Render\BubbleableMetadata;

/**
 * Implements hook_token_info().
 */
function building_custom_token_info() : array {
  $info = [];

  $info['types']['building_custom'] = [
    'name' => t('Building Custom Tokens'),
    'description' => t('Custom tokens to solve use-case problems for our website.'),
  ];

  $info['tokens']['building_custom']['image_caption'] = [
    'name' => 'Building Author Caption',
    'description' => t('This token will return the author and author location. To be used as caption with PhotoSwipe in Views')
  ];

  return $info;
}
/**
 * Implements hook_tokens().
 */
function building_custom_tokens($type, $tokens, array $data, array $options, BubbleableMetadata $bubbleable_metadata) : array {
  $replacements = [];

  if ($type == 'building_custom') {
    foreach ($tokens as $name => $original) {
      switch ($name) {
        case 'image_caption':
          $node = $data['node'];

          $text = '';
          if ($node->hasField('field_image_author') && !$node->get('field_image_author')->isEmpty()) {
            $text .= "<strong>Author</strong>:<br>" . $node->field_image_author->value . "<br>";
          }
          if ($node->hasField('field_author_location') && !$node->get('field_author_location')->isEmpty()) {
            $text .= "<strong>Location</strong>:<br>" . $node->field_author_location->value . "<br>";
          }

          $replacements[$original] = \Drupal\Core\Render\Markup::create($text);
          break;

        default:
          break;
      }
    }
  }

  return $replacements;

}

Can be used for example in Views, to format a PhotoSwipe image caption as below. The first three tokens are always available and safe to use, whereas "Author" and "Author location" are not, which is what [building_custom:image_caption] handles:

<h2>[node:field_building]</h2>
<hr>
<h4>[node:field_image_category]</h4>
[node:field_image_tags]
<hr>
[building_custom:image_caption]