Loop type: Post

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 "custom_field_compare" and "custom_field_value" attributes. 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
  
• ignore_sticky_posts - Ignore sticky posts
  Type: boolean
  Default: TRUE
  
• 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
  
• 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
  
• 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
  
• type - Post type(s)
  Type: string, array
  Default: post
  

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 as author_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 as image_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 as parent_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 - default 55
• 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