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.
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. |
andNotRelatedTo | Narrows the query results to only tags that are not related to certain other 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. |
eagerly | Causes the query to be used to eager-load results for the query’s source element and any other elements in its collection. |
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). |
inBulkOp | Narrows the query results to only tags that were involved in a bulk element operation. |
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. |
notRelatedTo | Narrows the query results to only tags that are not related to certain other elements. |
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. |
prepForEagerLoading | Prepares the query for lazy eager loading. |
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. |
render | Executes the query and renders the resulting elements using their partial templates. |
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. |
wasCountEagerLoaded | Returns whether the query result count was already eager loaded by the query's source element. |
wasEagerLoaded | Returns whether the query results were already eager loaded by the query's source element. |
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.
# andNotRelatedTo
Narrows the query results to only tags that are not related to certain other elements.
See Relations (opens new window) for a full explanation of how to work with this parameter.
{# Fetch all tags that are related to myCategoryA and not myCategoryB #}
{% set tags = craft.tags()
.relatedTo(myCategoryA)
.andNotRelatedTo(myCategoryB)
.all() %}
# 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.
{# 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.
# 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. |
{# 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. |
{# Fetch tags updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}
{% set tags = craft.tags()
.dateUpdated(">= #{lastWeek}")
.all() %}
# eagerly
Causes the query to be used to eager-load results for the query’s source element and any other elements in its collection.
# 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.
{# 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. |
# 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. |
{# 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. |
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).
# inBulkOp
Narrows the query results to only tags that were involved in a bulk element operation.
# 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.
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.
# limit
Determines the number of tags that should be returned.
# notRelatedTo
Narrows the query results to only tags that are not related to certain other elements.
See Relations (opens new window) for a full explanation of how to work with this parameter.
{# Fetch all tags that are related to myEntry #}
{% set tags = craft.tags()
.notRelatedTo(myEntry)
.all() %}
# 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
.)
{# 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.
{# 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() %}
# prepForEagerLoading
Prepares the query for lazy eager loading.
# 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.
{# Fetch all tags that are related to myCategory #}
{% set tags = craft.tags()
.relatedTo(myCategory)
.all() %}
# render
Executes the query and renders the resulting elements using their partial templates.
If no partial template exists for an element, its string representation will be output instead.
# 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.
{# 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.
# 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. |
{# 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. |
{# 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 . |
{# 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.
# uid
Narrows the query results based on the tags’ UIDs.
{# 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.
{# 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 . |
{# Get the requested URI #}
{% set requestedUri = craft.app.request.getPathInfo() %}
{# Fetch the tag with that URI #}
{% set tag = craft.tags()
.uri(requestedUri|literal)
.one() %}
# wasCountEagerLoaded
Returns whether the query result count was already eager loaded by the query's source element.
# wasEagerLoaded
Returns whether the query results were already eager loaded by the query's source element.
# 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.
{# 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.