Tag Conditions // Statamic Docs

Hot Tip!

Are you looking "if/else" conditions? You probably want this page: Antler's Logic & Conditions

Overview

Quite often you'll find that you don't want to fetch all entries from a collection, or all terms from a taxonomy. Conditions give the ability to fetch only the content that meets the criteria of your choosing.

For example, you may want to list all entries that aren't the one you're viewing, are after your birthday 🎂 but before Christmas 🎄, or have a custom field like pinned 📌 set to true. Piece of cake. Piece of crumb cake. 🥮

Note: These conditions currently apply to the collections, taxonomy, and users tags.

Syntax

The conditions syntax has 3 parts: the field name, the condition name, and the value.

{field_name}:{condition}="{value}"

Using a variable reference

If you prefix the field name with a colon, it will use the value of a variable in your view

:author:is="author"

Multiple values

You can pass multiple values by separating them with a pipe.

taxonomy:category="happy|radical"

Comparisons

For conditions where you're matching or comparing a value is or starts_with, you'd do:

{{ collection:blog title:starts_with="Once upon a time..." }}

<s:collection:blog
  title:starts_with="Once upon a time..."
>
 
</s:collection:blog>

Boolean

For boolean conditions like exists or null, specify a value of true:

{{ collection:blog hero_image:exists="true" }}

<s:collection:blog
  hero_image:exists="true"
>
 
</s:collection:blog>

For negative boolean conditions, don't use ="false". Instead, pick the inverse condition, like :exists instead of :doesnt_exist.

// Nope
{{ collection:articles related_articles:exists="false" }}
 
// Yup
{{ collection:articles related_articles:doesnt_exist="true" }}

// Nope
<s:collection:articles
  related_articles:exists="false"
>
</s:collection:articles>
 
// Yup
<s:collection:articles
  related_articles:doesnt_exist="true"
>
</s:collection:articles>

Multiple Conditions

Need multiple conditions? Yeah, we support that.

{{ collection:drinks type:is="tiki" ingredients:in="Orgeat" }}
    <a href="{{ url }}">
        {{ title }}
    </a>
{{ /collection:drinks }}

<s:collection:drinks
  type:is="tiki"
  ingredients:in="Orgeat"
>
  <a href="{{ $url }}">
    {{ $title }}
  </a>
<s:/collection:drinks>

Passing multiple values

To pass multiple values in a condition, separate them with | pipes.

{{ collection:drinks ingredients:in="rum|falernum" }}
    <a href="{{ url }}">
        {{ title }}
    </a>
{{ /collection:drinks }}

<s:collection:drinks
  ingredients:in="rum|falernum"
>
  <a href="{{ $url }}">
    {{ $title }}
  </a>
</s:collection:drinks>

Sub Fields

You can apply conditions to "sub fields", like date ranges:

event_date:
  start: 2023-12-01
  end: 2023-12-03

{{ collection:events :event_date.start="today" }}
{{ collection:events :event_date.end="today" }}

<s:collection:events
  :event_date.start="$today"
>
</s:collection:events>
 
<s:collection:events
  :event_date.end="$today"
>
</s:collection:events>

String Conditions

The following conditions apply to fields with data stored as strings.

Condition	Description
`is` / `equals`	Include if field is equal to value.
`not` / `isnt`	Include if field is not equal to value.
`exists` / `isset`	Include if field exists.
`doesnt_exist` / `is_empty` / `null`	Include if field doesn't exist.
`contains`	Include if field contains value.
`doesnt_contain`	Include if field doesn't contain value.
`in`	Include if field value is in the provided array.
`not_in`	Include if field value is not_in the provided array.
`starts_with`	Include if field starts with value.
`doesnt_start_with`	Include if field doesn't start with value.
`ends_with`	Include if field ends with value.
`doesnt_end_with`	Include if field doesn't end with value.
`gt`	Include if field is greater than value.
`gte`	Include if field is greater than or equal to value.
`lt`	Include if field is less than value.
`lte`	Include if field is less than or equal to value.
`matches` / `regex`	Include if field matches case insensitive regex.
`doesnt_match`	Include if field doesn't match case insensitive regex.
`is_alpha`	Include if field contains only alphabetical characters.
`is_numeric`	Include if field contains only numeric characters.
`is_alpha_numeric`	Include if field contains only alphanumeric characters.
`is_url`	Include if field is a valid URL.
`is_embeddable`	Include if field is an embeddable video URL.
`is_email`	Include if field is valid email address.
`is_after`	Include if field is after date.
`is_before`	Include if field is before date.
`is_numberwang`	Include if field is numberwang.

Taxonomy Conditions

Taxonomy conditions are a little bit different. They start with taxonomy:, followed by the taxonomy name, an optional modifier argument, and finally the term you're seeking.

taxonomy:{handle}:{modifier}="{term}"

Query Modifiers

You may optionally control the behavior of the condition filter by passing the desired modifier into the tag method call. If you don't set a modifier, it will use any by default.

Any (default)

Fetch all entries that have any of one or more taxonomy terms.

Not

Fetch all entries that don't have one or more taxonomy terms.

All

Fetch all entries that contain each of one or more taxonomy terms.

Examples

<!-- Get all featured articles -->
{{ collection:articles taxonomy:tags:any="featured" }}
{{ collection:articles taxonomy:tags="featured" }} (shorthand)
 
<!-- Get all but sports-related articles -->
{{ collection:articles taxonomy:tags:not="sports" }}
 
<!-- Get all "featured" articles about gaming
{{ collection:articles taxonomy:tags:all="gaming|featured" }}

<!-- Get all featured articles -->
<s:collection:articles taxonomy:tags:any="featured">
</s:collection:articles>
 
<s:collection:articles taxonomy:tags="featured"> (shorthand)
</s:collection:articles>
 
 
<!-- Get all but sports-related articles -->
<s:collection:articles taxonomy:tags:not="sports">
</s:collection:articles>
 
 
<!-- Get all "featured" articles about gaming -->
<s:collection:articles taxonomy:tags:all="gaming|featured">
</s:collection:articles>

Arguments

Argument	Description
`{handle}`	Handle of the Taxonomy you wish to query.
`{modifier}`	Control the behavior of the condition filtering. Available options: `all`, `not`, and `any`. Default: `any`.
`{term}`	Term(s) to query. You may pass multiple terms by separating them with `\|` pipe delimiters.

Snippets

Here are some common and useful conditions snippets to grab on your next project.

Exclude the current entry

:id:not="id"

Entries with specific "tags"

Assuming you have a taxonomy named "Tags"...

taxonomy:tags="review|colorful"

Show draft (unpublished) entries

status:is="draft"

Published before a specific date

Let's use Y2K as the example date.

date:is_before="2000-01-01"

Tag Conditions