Tags

You can create folksonomies for your entries, users, and assets using Tags. Tags are another type of element.

With the release of Craft 4.4, we began consolidating features of other element types into entries.

A comparable tags field UI has not yet been introduced for entries. If you or your clients value this authoring experience, it is safe to continue using tags!

As part of that process, we introduced a console command that can automate the conversion of tags to channel sections:

php craft entrify/tags myTagGroupHandle

Read more about this transition (opens new window) on our blog.

# Tag Groups

Before you can create tags, you must create Tag Groups to contain them.

To create a new tag group, go to Settings → Tags and click New Tag Group.

Each tag group holds a unique set of tags, and lets you define a custom set of fields that should be available to tags within the group. However, you don’t need to assign any fields to the Tag Group Field Layout in order to use the group.

There is no centralized editing view for tags (like there is for other element types), so fields you attach will only be editable via a slideout, after a tag has been created and assigned to a tag field.

# Assigning Tags

To assign tags to things (like Entries), you must create a Tags field and add it to a Field Layout.

Each Tags field is connected to a single tag group. Whatever you attach the field to (entries, assets, users, etc.) will be able to create new tags and create relations to any of the tags within that group.

# Querying Tags

You can fetch tags in your templates or PHP code using a tag query.

Twig
PHP

{# Create a new tag query #}
{% set myTagQuery = craft.tags() %}

Once you’ve created a tag query, you can set parameters on it to narrow down the results, and then execute it by calling .all(). An array of Tag (opens new window) objects will be returned.

See Element Queries to learn about how element queries work.

# Example

We can display a list of the tags in a “Blog Tags” tag group by doing the following:

Create a tag query with craft.tags().
Set the group parameter on it.
Fetch the tags with .all().
Loop through the tags using a for (opens new window) tag to create the list HTML.

{# Create a tag query with the 'group' parameter #}
{% set myTagQuery = craft.tags()
  .group('blogTags') %}

{# Fetch the tags #}
{% set tags = myTagQuery.all() %}

{# Display the tag list #}
<ul>
  {% for tag in tags %}
    <li><a href="{{ url('blog/tags/'~tag.id) }}">{{ tag.title }}</a></li>
  {% endfor %}
</ul>

# Parameters

Tag queries support the following parameters:

Param	Description
afterPopulate	Performs any post-population processing on elements.
andRelatedTo	Narrows the query results to only tags that are related to certain other elements.
asArray	Causes the query to return matching tags as arrays of data, rather than Tag (opens new window) objects.
cache	Enables query cache for this Query.
clearCachedResult	Clears the cached result (opens new window).
dateCreated	Narrows the query results based on the tags’ creation dates.
dateUpdated	Narrows the query results based on the tags’ last-updated dates.
fixedOrder	Causes the query results to be returned in the order specified by id.
group	Narrows the query results based on the tag groups the tags belong to.
groupId	Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs.
id	Narrows the query results based on the tags’ IDs.
ignorePlaceholders	Causes the query to return matching tags as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement() (opens new window).
inReverse	Causes the query results to be returned in reverse order.
language	Determines which site(s) the tags should be queried in, based on their language.
limit	Determines the number of tags that should be returned.
offset	Determines how many tags should be skipped in the results.
orderBy	Determines the order that the tags should be returned in. (If empty, defaults to `title ASC`.)
preferSites	If unique is set, this determines which site should be selected when querying multi-site elements.
prepareSubquery	Prepares the element query and returns its subquery (which determines what elements will be returned).
relatedTo	Narrows the query results to only tags that are related to certain other elements.
search	Narrows the query results to only tags that match a search query.
site	Determines which site(s) the tags should be queried in.
siteId	Determines which site(s) the tags should be queried in, per the site’s ID.
siteSettingsId	Narrows the query results based on the tags’ IDs in the `elements_sites` table.
title	Narrows the query results based on the tags’ titles.
trashed	Narrows the query results to only tags that have been soft-deleted.
uid	Narrows the query results based on the tags’ UIDs.
unique	Determines whether only elements with unique IDs should be returned by the query.
uri	Narrows the query results based on the tags’ URIs.
with	Causes the query to return matching tags eager-loaded with related elements.
withCustomFields	Sets whether custom fields should be factored into the query.

# `afterPopulate`

Performs any post-population processing on elements.

# `andRelatedTo`

Narrows the query results to only tags that are related to certain other elements.

See Relations (opens new window) for a full explanation of how to work with this parameter.

Twig
PHP

{# Fetch all tags that are related to myCategoryA and myCategoryB #}
{% set tags = craft.tags()
  .relatedTo(myCategoryA)
  .andRelatedTo(myCategoryB)
  .all() %}

# `asArray`

Causes the query to return matching tags as arrays of data, rather than Tag (opens new window) objects.

Twig
PHP

{# Fetch tags as arrays #}
{% set tags = craft.tags()
  .asArray()
  .all() %}

# `cache`

Enables query cache for this Query.

# `clearCachedResult`

Clears the cached result (opens new window).

# `dateCreated`

Narrows the query results based on the tags’ creation dates.

Possible values include:

Value	Fetches tags…
`'>= 2018-04-01'`	that were created on or after 2018-04-01.
`'< 2018-05-01'`	that were created before 2018-05-01.
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were created between 2018-04-01 and 2018-05-01.
`now`/`today`/`tomorrow`/`yesterday`	that were created at midnight of the specified relative date.

Twig
PHP

{# Fetch tags created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set tags = craft.tags()
  .dateCreated(['and', ">= #{start}", "< #{end}"])
  .all() %}

# `dateUpdated`

Narrows the query results based on the tags’ last-updated dates.

Possible values include:

Value	Fetches tags…
`'>= 2018-04-01'`	that were updated on or after 2018-04-01.
`'< 2018-05-01'`	that were updated before 2018-05-01.
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were updated between 2018-04-01 and 2018-05-01.
`now`/`today`/`tomorrow`/`yesterday`	that were updated at midnight of the specified relative date.

Twig
PHP

{# Fetch tags updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set tags = craft.tags()
  .dateUpdated(">= #{lastWeek}")
  .all() %}

# `fixedOrder`

Causes the query results to be returned in the order specified by id.

If no IDs were passed to id, setting this to true will result in an empty result set.

Twig
PHP

{# Fetch tags in a specific order #}
{% set tags = craft.tags()
  .id([1, 2, 3, 4, 5])
  .fixedOrder()
  .all() %}

# `group`

Narrows the query results based on the tag groups the tags belong to.

Possible values include:

Value	Fetches tags…
`'foo'`	in a group with a handle of `foo`.
`'not foo'`	not in a group with a handle of `foo`.
`['foo', 'bar']`	in a group with a handle of `foo` or `bar`.
`['not', 'foo', 'bar']`	not in a group with a handle of `foo` or `bar`.
a TagGroup (opens new window) object	in a group represented by the object.

Twig
PHP

{# Fetch tags in the Foo group #}
{% set tags = craft.tags()
  .group('foo')
  .all() %}

# `groupId`

Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs.

Possible values include:

Value	Fetches tags…
`1`	in a group with an ID of 1.
`'not 1'`	not in a group with an ID of 1.
`[1, 2]`	in a group with an ID of 1 or 2.
`['not', 1, 2]`	not in a group with an ID of 1 or 2.

Twig
PHP

{# Fetch tags in the group with an ID of 1 #}
{% set tags = craft.tags()
  .groupId(1)
  .all() %}

# `id`

Narrows the query results based on the tags’ IDs.

Possible values include:

Value	Fetches tags…
`1`	with an ID of 1.
`'not 1'`	not with an ID of 1.
`[1, 2]`	with an ID of 1 or 2.
`['not', 1, 2]`	not with an ID of 1 or 2.

Twig
PHP

{# Fetch the tag by its ID #}
{% set tag = craft.tags()
  .id(1)
  .one() %}

This can be combined with fixedOrder if you want the results to be returned in a specific order.

# `ignorePlaceholders`

Causes the query to return matching tags as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement() (opens new window).

# `inReverse`

Causes the query results to be returned in reverse order.

Twig
PHP

{# Fetch tags in reverse #}
{% set tags = craft.tags()
  .inReverse()
  .all() %}

# `language`

Determines which site(s) the tags should be queried in, based on their language.

Possible values include:

Value	Fetches tags…
`'en'`	from sites with a language of `en`.
`['en-GB', 'en-US']`	from sites with a language of `en-GB` or `en-US`.
`['not', 'en-GB', 'en-US']`	not in sites with a language of `en-GB` or `en-US`.

Elements that belong to multiple sites will be returned multiple times by default. If you only want unique elements to be returned, use unique in conjunction with this.

Twig
PHP

{# Fetch tags from English sites #}
{% set tags = craft.tags()
  .language('en')
  .all() %}

# `limit`

Determines the number of tags that should be returned.

Twig
PHP

{# Fetch up to 10 tags  #}
{% set tags = craft.tags()
  .limit(10)
  .all() %}

# `offset`

Determines how many tags should be skipped in the results.

Twig
PHP

{# Fetch all tags except for the first 3 #}
{% set tags = craft.tags()
  .offset(3)
  .all() %}

# `orderBy`

Determines the order that the tags should be returned in. (If empty, defaults to title ASC.)

Twig
PHP

{# Fetch all tags in order of date created #}
{% set tags = craft.tags()
  .orderBy('dateCreated ASC')
  .all() %}

# `preferSites`

If unique is set, this determines which site should be selected when querying multi-site elements.

For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to ['c', 'b', 'a'], then Foo will be returned for Site B, and Bar will be returned for Site C.

If this isn’t set, then preference goes to the current site.

Twig
PHP

{# Fetch unique tags from Site A, or Site B if they don’t exist in Site A #}
{% set tags = craft.tags()
  .site('*')
  .unique()
  .preferSites(['a', 'b'])
  .all() %}

# `prepareSubquery`

Prepares the element query and returns its subquery (which determines what elements will be returned).

# `relatedTo`

Narrows the query results to only tags that are related to certain other elements.

See Relations (opens new window) for a full explanation of how to work with this parameter.

Twig
PHP

{# Fetch all tags that are related to myCategory #}
{% set tags = craft.tags()
  .relatedTo(myCategory)
  .all() %}

# `search`

Narrows the query results to only tags that match a search query.

See Searching (opens new window) for a full explanation of how to work with this parameter.

Twig
PHP

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch all tags that match the search query #}
{% set tags = craft.tags()
  .search(searchQuery)
  .all() %}

# `site`

Determines which site(s) the tags should be queried in.

The current site will be used by default.

Possible values include:

Value	Fetches tags…
`'foo'`	from the site with a handle of `foo`.
`['foo', 'bar']`	from a site with a handle of `foo` or `bar`.
`['not', 'foo', 'bar']`	not in a site with a handle of `foo` or `bar`.
a craft\models\Site (opens new window) object	from the site represented by the object.
`'*'`	from any site.

If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use unique in conjunction with this.

Twig
PHP

{# Fetch tags from the Foo site #}
{% set tags = craft.tags()
  .site('foo')
  .all() %}

# `siteId`

Determines which site(s) the tags should be queried in, per the site’s ID.

The current site will be used by default.

Possible values include:

Value	Fetches tags…
`1`	from the site with an ID of `1`.
`[1, 2]`	from a site with an ID of `1` or `2`.
`['not', 1, 2]`	not in a site with an ID of `1` or `2`.
`'*'`	from any site.

Twig
PHP

{# Fetch tags from the site with an ID of 1 #}
{% set tags = craft.tags()
  .siteId(1)
  .all() %}

# `siteSettingsId`

Narrows the query results based on the tags’ IDs in the elements_sites table.

Possible values include:

Value	Fetches tags…
`1`	with an `elements_sites` ID of 1.
`'not 1'`	not with an `elements_sites` ID of 1.
`[1, 2]`	with an `elements_sites` ID of 1 or 2.
`['not', 1, 2]`	not with an `elements_sites` ID of 1 or 2.

Twig
PHP

{# Fetch the tag by its ID in the elements_sites table #}
{% set tag = craft.tags()
  .siteSettingsId(1)
  .one() %}

# `title`

Narrows the query results based on the tags’ titles.

Possible values include:

Value	Fetches tags…
`'Foo'`	with a title of `Foo`.
`'Foo*'`	with a title that begins with `Foo`.
`'*Foo'`	with a title that ends with `Foo`.
`'Foo'`	with a title that contains `Foo`.
`'not Foo'`	with a title that doesn’t contain `Foo`.
`['Foo', 'Bar']`	with a title that contains `Foo` or `Bar`.
`['not', 'Foo', 'Bar']`	with a title that doesn’t contain `Foo` or `Bar`.

Twig
PHP

{# Fetch tags with a title that contains "Foo" #}
{% set tags = craft.tags()
  .title('*Foo*')
  .all() %}

# `trashed`

Narrows the query results to only tags that have been soft-deleted.

Twig
PHP

{# Fetch trashed tags #}
{% set tags = craft.tags()
  .trashed()
  .all() %}

# `uid`

Narrows the query results based on the tags’ UIDs.

Twig
PHP

{# Fetch the tag by its UID #}
{% set tag = craft.tags()
  .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
  .one() %}

# `unique`

Determines whether only elements with unique IDs should be returned by the query.

This should be used when querying elements from multiple sites at the same time, if “duplicate” results is not desired.

Twig
PHP

{# Fetch unique tags across all sites #}
{% set tags = craft.tags()
  .site('*')
  .unique()
  .all() %}

# `uri`

Narrows the query results based on the tags’ URIs.

Possible values include:

Value	Fetches tags…
`'foo'`	with a URI of `foo`.
`'foo*'`	with a URI that begins with `foo`.
`'*foo'`	with a URI that ends with `foo`.
`'foo'`	with a URI that contains `foo`.
`'not foo'`	with a URI that doesn’t contain `foo`.
`['foo', 'bar']`	with a URI that contains `foo` or `bar`.
`['not', 'foo', 'bar']`	with a URI that doesn’t contain `foo` or `bar`.

Twig
PHP

{# Get the requested URI #}
{% set requestedUri = craft.app.request.getPathInfo() %}

{# Fetch the tag with that URI #}
{% set tag = craft.tags()
  .uri(requestedUri|literal)
  .one() %}

# `with`

Causes the query to return matching tags eager-loaded with related elements.

See Eager-Loading Elements (opens new window) for a full explanation of how to work with this parameter.

Twig
PHP

{# Fetch tags eager-loaded with the "Related" field’s relations #}
{% set tags = craft.tags()
  .with(['related'])
  .all() %}

# `withCustomFields`

Sets whether custom fields should be factored into the query.

Was this page helpful?

Parts of this page are generated or assembled by automations. While we greatly appreciate contributions to the documentation, reporting automated content issues will allow us to fix them at the source!

Tags

# Tag Groups

# Assigning Tags

# Querying Tags

# Example

# Parameters

# afterPopulate

# andRelatedTo

# asArray

# cache

# clearCachedResult

# dateCreated

# dateUpdated

# fixedOrder

# group

# groupId

# id

# ignorePlaceholders

# inReverse

# language

# limit

# offset

# orderBy

# preferSites

# prepareSubquery

# relatedTo

# search

# site

# siteId

# siteSettingsId

# title

# trashed

# uid

# unique

# uri

# with

# withCustomFields

Was this page helpful?

# `afterPopulate`

# `andRelatedTo`

# `asArray`

# `cache`

# `clearCachedResult`

# `dateCreated`

# `dateUpdated`

# `fixedOrder`

# `group`

# `groupId`

# `id`

# `ignorePlaceholders`

# `inReverse`

# `language`

# `limit`

# `offset`

# `orderBy`

# `preferSites`

# `prepareSubquery`

# `relatedTo`

# `search`

# `site`

# `siteId`

# `siteSettingsId`

# `title`

# `trashed`

# `uid`

# `unique`

# `uri`

# `with`

# `withCustomFields`