Tag List

The taglist field picks several values as tags, typed in or chosen from a list of options. It saves them as a JSON array, as one joined string, or as related records.

Modes

mode sets how the tags are saved, and when it is not set it follows the attribute:

• a relation uses relation mode, which saves the related records' keys;
• a JSON attribute uses array mode, which saves a JSON array;
• anything else uses string mode, which saves one string with the tags joined by separator.

A JSON attribute is listed in $jsonable on an October Rain model, or has an array cast on a plain Eloquent model. See Models for both.

/**
 * @var array<int, string> jsonable attributes stored as JSON for the structured fields.
 */
protected $jsonable = [
    'features',
    'permissions',
    'interests',
    'tags',
    'topics',
    'content',
    'steps',
    'address',
    'line_items',
    'meta',
    'shipping',
    'contact',
    'faqs',
    'highlights',
    'milestones',
    'dimensions',
    'sections',
    'specs',
    'itinerary',
    'languages',
    'deliveries',
    'variants',
    'stockists',
    'parts',
    'price_breaks',
    'bundle_items',
    'suppliers',
    'components',
    'stock_levels',
    'reviews',
    'spec_sheet',
    'certifications',
    'awards',
    'seo',
    'packaging',
];

Array mode

mode: array saves the tags as a JSON array, such as ["red", "blue"]. tags is already in $jsonable, so the mode would follow anyway, and setting it makes the choice explicit. customTags lets the user type new tags, each ended with Enter or the separator, a comma by default. placeholder fills the field while it is empty.

fields:
    tags:
        label: Tags
        type: taglist
        mode: array
        customTags: true
        placeholder: Type a tag and press Enter
        comment: Typed tags saved as a JSON array.

String mode

String mode joins the tags into one value with separator, either comma (the default) or space, and splits the saved value the same way when the form loads. The separator also ends a typed tag, so here a space finishes each keyword.

fields:
    keywords:
        label: Keywords
        type: taglist
        mode: string
        separator: space
        customTags: true
        placeholder: Type keywords
        comment: Typed tags saved as one string, separated by spaces.

Fixed options

options limits the tags to a fixed list, saved by their keys, such as ["design", "research"]. Like a dropdown's options, it takes an inline list, the name of a model method that returns them, or true to call the model's get{Field}Options() method. maxItems caps how many tags can be picked.

fields:
    topics:
        label: Topics
        type: taglist
        maxItems: 3
        placeholder: Pick up to three topics
        options:
            design: Design
            engineering: Engineering
            marketing: Marketing
            research: Research
            support: Support
        comment: Fixed options saved by their keys, three at most.

Saving labels

useKey: false saves the option labels instead of their keys, here ["English", "Japanese"]. Custom tags always save the text that was typed, so customTags turns useKey off.

fields:
    languages:
        label: Languages
        type: taglist
        useKey: false
        placeholder: Pick languages
        options:
            en: English
            fr: French
            ja: Japanese
            pt: Portuguese
        comment: Fixed options saved by their labels instead of their keys.

Relation mode

On a relation, such as this belongsToMany relation to UserGroup, the options are every record of the related model, named by its nameFrom column, and saving syncs the relation to the picked records.

fields:
    groups:
        label: Groups
        type: taglist
        nameFrom: name
        placeholder: Add groups
        comment: Picks from every group and saves the relation.

/**
 * @var array<string, mixed> belongsToMany relations, the groups, categories and labels picked by checkbox and tag lists.
 */
public $belongsToMany = [
    'groups' => [UserGroup::class, 'table' => 'sample_user_group'],
    'categories' => [Category::class, 'table' => 'category_sample'],
    'labels' => [Tag::class, 'table' => 'sample_tag'],
];

On a plain Eloquent model, sync the relation in your save handler, as the relation field shows.

Creating related records

With customTags in relation mode, the field matches tags to records by their nameFrom column, and a typed tag that matches no record creates one, setting only that column. The new record is saved without validation, so the related model's other columns must accept empty values. When the field also sets options, it cannot create records, and saving a tag that matches none of the options throws an error.

fields:
    labels:
        label: Labels
        type: taglist
        nameFrom: name
        customTags: true
        placeholder: Pick a tag or type a new one
        comment: A typed tag that does not exist yet is created as a new tag record.

Read-only

readOnly lists the tags without an input, and still posts them from hidden inputs. This copy reads the tags through valueFrom, and its name starts with an underscore, which keeps it out of the saved data.

fields:
    _tags_readonly:
        label: Tags
        type: taglist
        valueFrom: tags
        readOnly: true
        customTags: true
        comment: Lists the tags without an input, and still posts them.

Preview

disabled lists the picked labels in preview mode, and the field is left out of the save.

fields:
    topics_preview:
        label: Topics
        type: taglist
        valueFrom: topics
        disabled: true
        options:
            design: Design
            engineering: Engineering
            marketing: Marketing
            research: Research
            support: Support
        comment: Lists the picked topics as a preview, which is never saved.

Options

Option	Description
mode	how the tags are saved: array, string or relation. Default: follows the attribute.
separator	the character that joins the tags in string mode and ends a typed tag: comma or space. Default: comma.
customTags	lets the user type new tags. In relation mode a new tag creates a record. Default: false.
options	a fixed list of tags, the name of a model method that returns them, or true for get{Field}Options(). Default: the related records in relation mode, otherwise none.
useKey	saves the option keys rather than their labels. Turned off by customTags. Default: true.
nameFrom	in relation mode, the related model's column that names each tag. Default: name.
placeholder	the text shown while the field is empty. Default: none.
maxItems	the most tags that can be picked. Default: no limit.

The field also takes the common field properties, such as readOnly, disabled and valueFrom.