For loop type post
, page
, and custom post type, here are the query parameters and fields.
Query parameters
-
author
- Include by author ID, login name, or "current"
Type: string, array
-
category
- Include by category ID, slug, or "current"
Type: string, array
-
child_terms
- Set "true" to include child terms for hierarchical taxonomies
Type: string
-
custom_date_field
- Filter by given custom date field. See filtering the loop for information on when this attribute should be used.
Type: string
The example below will display posts in an "event" custom post type that has an "event_date_time" custom field before the current date (i.e. past events)
<Loop type=event custom_date_field=event_date_time custom_date_field_format="Y-m-d H:i:s" custom_date_field_compare=before custom_date_field_value=current>
-
custom_date_field_compare
- Compare using one of: "equal" (default), "not", "before", "before_inclusive", "after", "after_inclusive"
Type: string
-
custom_date_field_format
- For custom date field query, specify the date format of the field value - Default is "Ymd"; For date-time field, set "Y-m-d H:i:s". If it's a timestamp, use "timestamp". For custom field plugins other than ACF, you may need to use a different format.
Type: string
-
custom_date_field_type
- For custom date field query, one of: date (default), time, datetime, number
Type: string
-
custom_date_field_value
- Filter by given custom date field value, or "current"
Type: string
-
custom_field
- Filter by given custom field. Use with the "custom_field_compare", "custom_field_value", and "custom_field_type" parameters. See filtering the loop for information on when this attribute should be used.
Type: string
The example below will display posts that have a "news_type" custom field that is not equal to "exclusive."
<Loop type=post custom_field=news_type custom_field_compare=not custom_field_value=exclusive>
-
custom_field_2
- See attribute "custom_field"
Type: string
-
custom_field_3
- See attribute "custom_field"
Type: string
-
custom_field_compare
- Compare using one of: "equal" (default), "not", "before", "before_inclusive", "after", "after_inclusive"
Type: string
-
custom_field_compare_2
- See attribute "custom_field_compare"
Type: string
-
custom_field_compare_3
- See attribute "custom_field_compare"
Type: string
-
custom_field_type
- For custom field query, one of: string (default), number, date, time, datetime
Type: string
-
custom_field_type_2
- See attribute "custom_field_type"
Type: string
-
custom_field_type_3
- See attribute "custom_field_type"
Type: string
-
custom_field_value
- Filter by given custom field value
Type: string
-
custom_field_value_2
- See attribute "custom_field_value"
Type: string
-
custom_field_value_3
- See attribute "custom_field_value"
Type: string
-
exclude
- Exclude by ID or name
Type: string, array
-
exclude_author
- Exclude by author ID, login name, or "current"
Type: string, array
-
exclude_category
- Exclude by category ID, slug, or "current"
Type: string, array
-
exclude_parent
- Exclude by parent ID or name
Type: string, array
-
exclude_tag
- Exclude by tag ID, slug, or "current"
Type: string, array
-
id
- Get posts by ID(s)
Type: string, array -
include
- Include by ID or name
Type: string, array
-
include_children
- Include children
Type: boolean
-
name
- Name/slug
Type: string, array
-
order
- Order: asc (ascending) or desc (descending)
Type: string
Default:asc
-
orderby
- Order by one of: id, author, title, name, type, date, modified, random, comment_count, relevance, menu
Type: string
Default:title
-
orderby_field
- Order by custom field
Type: string
-
orderby_field_number
- Order by custom field whose value is a number
Type: string
-
page
- Page number
Type: number
Default:1
-
paged
- Posts per page
Type: number
Default:-1
-
parent
- Include by parent ID or name
Type: string, array
-
post_type
- Filter by specific post type(s), either core post types like "post" and "page" or custom post types, even those added by third-party plugins.
Type: string, array
Default:post
-
publish_compare
- Publish date comparison - One of: "before", "before_inclusive", "after", "after_inclusive"
Type: string
-
publish_date
- Filter by publish date in Y-M-D format, "today", "X days ago" and other values compatible with strtotime() - Optionally use "publish_compare" attribute
Type: string
The example below will display posts that have been published in the past two weeks.
<Loop type=post publish_compare="after" publish_date="2 weeks ago">
-
publish_day
- Filter by given publish day of the month, from 1 to 31, or "current"
Type: number
-
publish_month
- Filter by given publish month, from 1 to 12, or "current"
Type: number
-
publish_week
- Filter by given publish week, from 1 to 54, or "current" - Note: the "publish_compare" attribute is not supported for this field
Type: number
-
publish_year
- Filter by given publish year, or "current"
Type: number
-
search
- Search by given keyword - Prepending a keyword with a hyphen "-" will exclude posts matching it
Type: string
The example below will display posts in a "course" custom post type that match a search, where the value of that search is defined by a URL query called "keywords."
<Loop type=course search="{Url query=keywords}">
-
status
- Post status: publish (default), pending, draft, future, private, trash
Type: string, array
Default:publish
-
sticky
- Affects the behavior of sticky posts. Set equal to "true" to put sticky posts at the beginning of the loop, "false" to exclude sticky posts from the loop, and "only" to loop through only sticky posts and ignore non-sticky posts.
Type: string
-
tag
- Include by tag ID, slug, or "current"
Type: string, array
-
taxonomy
- Include by taxonomy ID, slug, or "current" for taxonomy archive
Use with "terms" and "taxonomy_compare" attributes
Type: string, number
-
taxonomy_2
- See attribute "taxonomy"
Type: string, number
-
taxonomy_3
- See attribute "taxonomy"
Type: string, number
-
taxonomy_compare
- One of "in" (default), "not", "and", "exists", and "not exists"
Use with "taxonomy" attribute
Type: string
The example below will display posts in an "agency" custom post type that have both the taxonomy terms "marketing" and "creative" applied to them in a custom taxonomy called "expertise"
<Loop type=agency taxonomy=expertise taxonomy_compare=and terms=marketing,creative>
-
taxonomy_compare_2
- See attribute "taxonomy_compare"
Type: string
-
taxonomy_compare_3
- See attribute "taxonomy_compare"
Type: string
-
taxonomy_relation
- When using more than one "taxonomy" queries, can specify "and" or "or"
Type: string
The example below will display posts in an "event" custom post type that have the category term "seminar" applied and also don't have either the terms "workshop" or "training" applied.
<Loop type=event taxonomy=category taxonomy_compare=exists terms=seminar taxonomy_relation=and taxonomy_2=category taxonomy_compare_2=not terms_2=workshop,training>
-
terms
- Include by taxonomy term ID, slug, or "current"
Use with "taxonomy" attribute
Type: string, number, array
The example below will display posts in the "opinions" category.
<Loop type=post taxonomy=category terms=opinions>
-
terms_2
- See attribute "terms"
Type: string, number, array
-
terms_3
- See attribute "terms"
Type: string, number, array
Fields
-
all
- Show all custom fields (for development purposes)
-
ancestors
- Ancestor posts from lowest to highest level; Set reverse=true to go from top-level down
-
archive_author
- On an author archive page, looping through this field creates a user loop of the current author
-
archive_post_type
- On a post type archive page, looping through this field creates a post loop of the current post type
-
archive_term
- On a taxonomy archive page, looping through this field creates a taxonomy term loop of the current term
-
author
- Author
-
author_*
- Author's user field where the asterisk can be replaced with any field from the user loop such asauthor_avatar_url
.
-
children
- Children
-
children_ids
- Children IDs
-
content
- Content
-
edit_url
- Edit URL
-
excerpt
- Excerpt
-
id
- ID
-
image
- Featured image
-
image_*
- Featured image field where the asterisk can be replaced with any field from the attachment loop such asimage_url
.
-
menu_order
- Menu order
-
modify_date
- Modify date
-
name
- name/slug
-
parent
- Parent
-
parent_*
- Parent field where the asterisk can be replaced with any field from the post loop such asparent_title
.
-
parent_ids
- All parent IDs from current to top
-
post_class
- Post classes
-
publish_date
- Publish date
-
status
- Status
-
title
- Title -
url
- URL
Excerpt
For post excerpts, the attribute auto=true
can be used to optionally generate an excerpt from post content for posts that don't already have content in their excerpt field.
<Field excerpt auto=true />
Attributes to customize:
-
words
Maximum number of words - default55
-
more
Text to display after content is trimmed - default:[…]
Examples
- How to display a random post when your hosting provider has disabled random sorting
-
How to display a custom field that contains an image
-
How to create loops within loops within loops
-
How to only show posts with a certain custom field filled out
-
How to show posts only if they exist and display a message if they don’t exist
-
How to adjust the resolution or size of a featured image
-
How to display a post editing link only when the current user is the post's author
-
How to display term fields on a taxonomy term archive