8.5.x token.api.php hook_token_info()
8.0.x token.api.php hook_token_info()
8.1.x token.api.php hook_token_info()
8.2.x token.api.php hook_token_info()
8.3.x token.api.php hook_token_info()
8.4.x token.api.php hook_token_info()
8.6.x token.api.php hook_token_info()
7.x system.api.php hook_token_info()

Provide information about available placeholder tokens and token types.

Tokens are placeholders that can be put into text by using the syntax [type:token], where type is the machine-readable name of a token type, and token is the machine-readable name of a token within this group. This hook provides a list of types and tokens to be displayed on text editing screens, so that people editing text can see what their token options are.

The actual token replacement is done by token_replace(), which invokes hook_tokens(). Your module will need to implement that hook in order to generate token replacements from the tokens defined here.

Return value

An associative array of available tokens and token types. The outer array has two components:

  • types: An associative array of token types (groups). Each token type is an associative array with the following components:

    • name: The translated human-readable short name of the token type.
    • description: A translated longer description of the token type.
    • needs-data: The type of data that must be provided to token_replace() in the $data argument (i.e., the key name in $data) in order for tokens of this type to be used in the $text being processed. For instance, if the token needs a node object, 'needs-data' should be 'node', and to use this token in token_replace(), the caller needs to supply a node object as $data['node']. Some token data can also be supplied indirectly; for instance, a node object in $data supplies a user object (the author of the node), allowing user tokens to be used when only a node data object is supplied.
  • tokens: An associative array of tokens. The outer array is keyed by the group name (the same key as in the types array). Within each group of tokens, each token item is keyed by the machine name of the token, and each token item has the following components:

    • name: The translated human-readable short name of the token.
    • description: A translated longer description of the token.
    • type (optional): A 'needs-data' data type supplied by this token, which should match a 'needs-data' value from another token type. For example, the node author token provides a user object, which can then be used for token replacement data in token_replace() without having to supply a separate user object.

See also



Related topics

7 functions implement hook_token_info()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

comment_token_info in modules/comment/comment.tokens.inc
Implements hook_token_info().
node_token_info in modules/node/node.tokens.inc
Implements hook_token_info().
poll_token_info in modules/poll/poll.tokens.inc
Implements hook_token_info().
statistics_token_info in modules/statistics/statistics.tokens.inc
Implements hook_token_info().
system_token_info in modules/system/system.tokens.inc
Implements hook_token_info().

... See full list

1 invocation of hook_token_info()
token_info in includes/token.inc
Returns metadata describing supported tokens.


modules/system/system.api.php, line 4565
Hooks provided by Drupal core and the System module.


function hook_token_info() {
  $type = array(
    'name' => t('Nodes'),
    'description' => t('Tokens related to individual nodes.'),
    'needs-data' => 'node',

  // Core tokens for nodes.
  $node['nid'] = array(
    'name' => t("Node ID"),
    'description' => t("The unique ID of the node."),
  $node['title'] = array(
    'name' => t("Title"),
    'description' => t("The title of the node."),
  $node['edit-url'] = array(
    'name' => t("Edit URL"),
    'description' => t("The URL of the node's edit page."),

  // Chained tokens for nodes.
  $node['created'] = array(
    'name' => t("Date created"),
    'description' => t("The date the node was posted."),
    'type' => 'date',
  $node['author'] = array(
    'name' => t("Author"),
    'description' => t("The author of the node."),
    'type' => 'user',
  return array(
    'types' => array(
      'node' => $type,
    'tokens' => array(
      'node' => $node,


manimejia’s picture

Invoked by function token_info(). See file token.inc for more info.

Aeternum’s picture

Just an example on how to use this function to define a new token type:

function yourmodulename_token_info()
  $info['tokens']['user']['machine_name_of_your_token'] = array(
    'name' => t('Your token name'),
    'description' => t('The description of your token name'),

  return $info;
woop_light’s picture

Thanks. How would I add it to the node type rather than making it custom?

EDIT: here's the answer.

function MYMODULENAME_token_info() {
  $info['tokens']['node']['first_letter'] = array(
    'name' => t('First Letter'),
    'description' => t("The first letter of the node title."),
  return $info;

this will make it show up in your list of tokens under 'nodes'.

pferlito’s picture

This is a new token on the user type, not a new token type.

pcambra’s picture

marcoscano’s picture

Even if it's not mentioned here, when you are defining a generic token, you may ommit the "needs-data" component.

zorroposada’s picture

I wanted to display or present my custom group of tokens as a nested list in the Token browser.
I created a custom module and implemented hook_token_info and hook_tokens
I was able to see my custom group of tokens but I wanted to add groups inside my group like:

Custom Group
- Token 1 -> [custom_group:token1]
- Token 2 -> [custom_group:token2]
- Sub Group 1 -> [custom_group:sub_group1]
-- Token 3 -> [custom_group:sub_group1:token3]
-- Token 4 -> [custom_group:sub_group1:token4]

This is possible if you set "needs-data" to point to my "custom_group" as follows

// inside hook_token_info

$info['types']['custom_group'] = array( // define main group
  'name' => t('Custom Group'),
  'description' => t('Custom Group'), 
$info['tokens']['custom_group']['token1'] = array( // first level token
  'name' => t('Token 1'),
  'description' => t('Token 1'), 
// ... more tokens

$info['types']['sub_group1'] = array( // define first nested group
  'name' => t('Sub Group 1'),
  'description' => t('Sub Group 1'),
  'needs-data' => 'custom_group', // tells drupal to nest this type inside custom_group
$info['tokens']['custom_group']['sub_group1'] = array( // define sub group as first level token
  'name' => t('Sub Group 1'),
  'description' => t('Sub Group 1'), 
  'type' => 'sub_group1', // tells drupal that this token belongs to sub_group1
$info['tokens']['sub_group1']['token3'] = array( // second level token
  'name' => t('Token 3'),
  'description' => t('Token 3'), 
// ... more tokens

fcastand’s picture

I test the following code but it doesn't appear in the list of tokens availables in token/help. It is Normal?
function yourmodulename_token_info()
$info['tokens']['user']['machine_name_of_your_token'] = array(
'name' => t('Your token name'),
'description' => t('The description of your token name'),

return $info;


hyperlinked’s picture

I'm not sure what you're looking at in Token help. My token help has a useless README page and that's all.

I had some problems with this myself. If you're having the same issue, I'll describe my epiphany to you. I wanted to add an extra token to the user welcome email. I have a custom module and after implenting hook_token_info(), I saw the name of the token appear when I browsed the list of available tokens when editing the welcome email, but I didn't add the token to the email at that time.

I then went to my hook_tokens() instance and did a dpm on the $tokens array expecting to see the machine name of my token value as a key in the $tokens array. What I didn't realize is that the $tokens array reflects the tokens that are being called by the content where the tokens are to be applied. Once I added [current-user:my-token-name] to the welcome email, the expected token key appeared.

I went around in circles trying everything thinking that I did it wrong or made an invisible typo. I hope this saves someone the same frustration.

Anu Anusha’s picture

Make sure that you enable your custom token globally available(admin/config/content/token_insert) in the interface after flushing the cache.

cravecode’s picture

To render a token with a "?" at the end, indicating that it accepts arguments, specify '"dynamic" => true' when defining your token.

drugget’s picture

Easy example how to create a custom node token
(found here: http://web-tricks.org/content/drupal-7-how-create-custom-node-token):

function MYMODULE_token_info() {
  $info['tokens']['node']['title_first_letter'] = array(
    'name' => t('Title first letter'),
    'description' => t('Generates first letter of node title')
  return $info;

function slideaway_currency_tokens($type, $tokens, array $data = array(), array $options = array()) {
  $replacements = array();
  if ($type == 'node' && !empty($data['node'])) {
    $node = $data['node'];
    foreach ($tokens as $name => $original) {
      switch ($name) {
        case 'title_first_letter':
          $replacements[$original] = substr($node->title, 0, 1); // get first letter of the title here 
  return $replacements;