---
title: "Token Field"
description: "The Pro Token Field control lets editors search a list of choices and add them as removable tags. The block gets an array of values, labels or both."
url: "https://www.lazyblocks.com/docs/blocks-controls/token-field/"
lastUpdated: 2026-09-23
source: "blocks-controls/token-field.mdx"
---
# Token Field [Pro]

Token Field control provides a tag-style input for selecting multiple values from predefined choices. Users can type to search and select options, which appear as removable tokens/tags.

## Control Settings

- **Choices** (`choices`) - a `Label` and a `Value` for each option, added with **+ Add Choice**. Empty by default
- **Allow Custom Values** (`allow_custom`) - off by default. On, a value typed into the field is kept even when no choice matches it
- **Multiple** (`multiple`) - on by default. Allows selecting more than one value
- **Output Format** (`output_format`) - `Value` by default:
  - `Value` - Returns option value
  - `Label` - Returns option label
  - `Both (Array)` - Returns object with both value and label

To add options, fill the Choices setting the same way as Select or Radio controls:

## Usage Examples

### Multiple Selection (Default)

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <ul class="tags-list">
        <?php foreach ( $attributes['control_name'] as $value ) : ?>
            <li class="tag tag-<?php echo esc_attr( $value ); ?>">
                <?php echo esc_html( $value ); ?>
            </li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <ul class="tags-list">
    {{#each control_name}}
      <li class="tag tag-{{this}}">{{this}}</li>
    {{/each}}
  </ul>
{{/if}}
```

### Single Selection

When Multiple is disabled, the control returns a single value:

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <span class="selected-tag">
        <?php echo esc_html( $attributes['control_name'] ); ?>
    </span>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <span class="selected-tag">{{control_name}}</span>
{{/if}}
```

### Label Output Format

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <div class="selected-labels">
        <?php foreach ( $attributes['control_name'] as $label ) : ?>
            <span class="label"><?php echo esc_html( $label ); ?></span>
        <?php endforeach; ?>
    </div>
<?php endif; ?>
```

### Array Output Format

When using "Both (Array)" format, each item contains both value and label:

```php title="PHP" /$attributes['control_name']/
<?php if ( $attributes['control_name'] ) : ?>
    <ul class="features-list">
        <?php foreach ( $attributes['control_name'] as $item ) : ?>
            <li class="feature-<?php echo esc_attr( $item['value'] ); ?>">
                <?php echo esc_html( $item['label'] ); ?>
            </li>
        <?php endforeach; ?>
    </ul>
<?php endif; ?>
```

```hbs title="Handlebars" /control_name/
{{#if control_name}}
  <ul class="features-list">
    {{#each control_name}}
      <li class="feature-{{this.value}}">
        {{this.label}}
      </li>
    {{/each}}
  </ul>
{{/if}}
```

### Post Meta

```php title="Post Meta" /get_lzb_meta( 'control_meta_name' )/
<?php
$values = get_lzb_meta( 'control_meta_name' );
if ( $values && is_array( $values ) ) {
    echo '<div class="meta-tags">';
    foreach ( $values as $value ) {
        printf(
            '<span class="meta-tag">%s</span>',
            esc_html( $value )
        );
    }
    echo '</div>';
}
?>
```

## Documentation Index
> Fetch the complete documentation index at: https://www.lazyblocks.com/llms.txt
> Fetch every page in a single file at: https://www.lazyblocks.com/llms-full.txt