An organized list of parameters for use with the [grid] shortcode
Mai Theme includes the [grid] shortcode for powerful and dynamic layouts. Grid can be used on any post type or templates to format a variety of content types into a grid.
Shortcode
[grid content="post"]
POPULAR EXAMPLES
Note: Many examples use post, category, or term Object IDs.
Posts by ID
[grid content="post" ids="123, 456"]
Pages by ID
[grid content="page" ids="123, 456"]
Recent Posts by Category
Option 1
[grid content="post" categories="123, 456"]
Option 2
[grid content="post" taxonomy="category" terms="123, 456"]
Option 3
[grid content="post" taxonomy="category" tax_field="slug" terms="recipes"]
Recent Posts by Tag
Option 1
[grid content="post" tags="123, 456"]
Option 2
[grid content="post" taxonomy="post_tag" terms="123, 456"]
Option 3
[grid content="post" taxonomy="post_tag" tax_field="slug" terms="my-tag-slug-here"]
Testimonials via Mai Testimonials add-on plugin
[grid content="testimonial" columns="1" slider="true" arrows="true" dots="true" fade="true"]
Testimonials by Testimonial Category via Mai Testimonials add-on plugin
[grid content="testimonial" taxonomy="testimonial_cat" terms="456, 789" columns="1" slider="true" arrows="true" dots="true" fade="true"]
[grid content="testimonial" taxonomy="testimonial_cat" tax_field="slug" terms="featured" columns="1" slider="true" arrows="true" dots="true" fade="true"]
Favorites via Mai Favorites add-on plugin
[grid content="favorite"]
Favorites by Favorites Category via Mai Favorites add-on plugin
[grid content="favorite" taxonomy="favorite_cat" terms="456, 789"]
[grid content="favorite" taxonomy="favorite_cat" tax_field="slug" terms="recommended-products"]
Related Posts
(works well in After Entry widget area)
[grid content="post" taxonomy="category" terms="current" exclude_current="true" number="6" gutter="xs" align_text="center"]
WooCommerce “Featured Products”
[grid content="product" taxonomy="product_visibility" tax_field="name" terms="featured" columns="4" number="4" show="image, title, price, add_to_cart" align_text="center" image_size="woocommerce_thumbnail"]
Child pages of current Page
[grid content="page" parent="current" number="all"]
Child pages of a specific Page
By page slug
[grid content="page" parent="our-attorneys" number="all"]
By page ID
[grid content="page" parent="456" number="all"]
Categories sorted alphabetically
[grid content="category" order_by="name" order="ASC"]
Child Categories of a specific Category
[grid content="category" parent="456" number="all"]
[grid content="category" parent="recipes" number="all"]
REQUIRED PARAMETERS
[grid] shortcode only has 1 required parameter.
content
- Type: string
- Default: post
- Description: Define grid content by post_type or taxonomy. Accepts a comma-separated list of registered post type or taxonomy names.
- Example:
[grid content="page"]
,[grid content="favorite"]
,[grid content="category"]
,[grid content="product_cat"]
GENERAL PARAMETERS
All of the parameters have defaults set, so you only need to use them for custom display. There are also more advanced grid parameters for even further customizations.
align_text
- Type: string
- Description: Aligns the text within columns horizontally and vertically with no effect on the columns. Accepts comma separated values for horizontal and vertical alignment. Accepted values are “left”, “center”, “right”, “top”, “middle”, “bottom”. Works great to center text, especially when image_location=”bg”.
- Example:
[grid content="post" align_text="center, middle"]
boxed
- Type: boolean
- Description: Display entries in a boxed or seamless look.
- Example:
[grid content="post" boxed="false"]
columns
- Type: integer
- Default: 3
- Description: The number of columns to display. Accepts “1”, “2”, “3”, “4” or “6”.
- Example:
[grid content="post" columns="4"]
categories
- Type: integer(s), comma separated
- Description: Show posts for defined Post categories. Accepts a comma-separated list of category IDs. Does not include child categories in hierarchical category structures. To show posts in another taxonomy, (tags, custom taxonomies, etc) you need to use taxonomy and terms parameters.
- Example:
[grid content="post" categories="16, 7"]
To show posts that include child categories you need to use taxonomy/terms parameters like this:[grid content="post" taxonomy="category" terms="16" tax_include_children="true"]
content_limit
- Type: integer
- Description: Limit number of words displayed when show=”excerpt” or show=”content” is used.
- Example:
[grid content="post" content_limit="50"]
grid_title
- Type: string
- Description: Add a grid title.
- Example:
[grid content="post" grid_title="Animals"]
ids
- Type: integer(s), comma-separated
- Description: Display specific posts or terms. Accepts a comma-separated list of post/term IDs. Content must match what you are trying to display.
post
must use post ID’s forids
parameter. - Example:
[grid content="post" ids="345, 1320"]
number
- Type: integer
- Default: 12
- Description: The number of posts to display. Use “all” to display all posts.
- Example:
[grid content="post" number="15"]
,[grid content="post" number="all"]
order
- Type: string
- Description: Order posts by ascending or descending order. Accepted values are “ASC” and “DESC”.
- Example:
[grid content="post" order="ASC"]
order_by
- Type: string
- Description: Sort retrieved posts by parameter.
- Example:
[grid content="post" order_by="author"]
,[grid content="post" order_by="menu_order"]
,[grid content="post" order_by="rand"]
(some hosts may disable “rand” – I’m looking at you WP Engine). To order entries by the order of IDs in theids
parameter useorder_by="post__in"
(note there are 2 underscores between post and in) when content is a post/page/cpt andorder_by="include"
when content is a category/tag/taxonomy.
parent
- Type: string, integer
- Description: Set the parent to the current page, a page/post/term ID, or a page/post/term slug. Great for displaying child pages of the current page. To only show top level pages/terms, use
parent="0"
- Example:
[grid content="page" parent="current"]
,[grid content="page" parent="234"]
, `[grid content="category" parent="recipes"]
show
- Type: string
- Default: title, image
- Description: Accepts a comma-separated list of attributes to show.
- Example:
[grid content="post" show="image, title, date, author, content, excerpt, more_link, meta"]
slider
- Type: boolean
- Default: false
- Description: Display posts in a horizontally scrollable slider, instead of rows.
- Example:
[grid content="post" slider="true"]
ADVANCED PARAMETERS
Most users will never need to use most of the available parameters. Below is a list of additional parameters that can be used with the grid shortcode.
align
- Type: string, comma-separated
- Description: Align columns and the text within the columns horizontally and vertically within the content area. Accepts a space-separated list of values in any order. Accepted values are (left, center, or right) and (top, middle, or bottom). This overrides align_cols and align_text if used.
- Example:
[grid content="post" align="center, middle"]
align_cols
- Type: string
- Description: Aligns columns within the content area, with no effect on the text within. Accepts a comma-separated list of values in any order. Accepted values are (“left”, “center”, or “right”) and (“top”, “middle”, or “bottom”).
- Example:
[grid content="post" align_cols="center, middle"]
author_after
- Type: string
- Description: The content to display after the post author name. Requires “author” to be in the “show” parameter.
- Example:
[grid content="post" author_after=" - "]
author_before
- Type: string
- Description: The content to display before the post author name. Requires “author” to be in the “show” parameter.
- Example:
[grid content="post" author_before="Written by: "]
authors
- Type: string
- Description: Show content from a specific author or authors. Accepts a comma-separated list of author IDs
- Example:
[grid content="post" authors="1, 12"]
bottom
- Type: integer
- Default: null
- Description: The amount of bottom margin/spacing on each grid entry. Accepts “none”, “xxxs”, “xxs”, “xs”, “sm”, “md”, “lg”, “xl”, or “xxl”
- Example:
[grid content="post" bottom="lg"]
class
- Type: string
- Description: Add additional HTML classes to the main grid HTML.
- Example:
[grid content="post" class="some-class another-class"]
content_type
- Type: string
- Description: Grid automatically configures this value based on the value of the “content” parameter. If you run into an issue where a post_type and a taxonomy are registered with the exact same name, you may need to manually set the content_type value. Accepts the values “post” for all post types, or “term” for all taxonomies.
- Example:
[grid content="post" content_type="post"]
date_after
- Type: string
- Description: The content to display after the post date.
- Example:
[grid content="post" date_after=" - "]
date_before
- Type: string
- Description: The content to display before the post date.
- Example:
[grid content="post" date_before="Published: "]
date_format
- Type: string
- Description: Configure output date formatting. Uses PHP date() format.
- Example:
[grid content="post" date_format="M j, Y"]
date_query_after
- Type: string
- Description: Get posts published after a date. Use any value strtotime() accepts.
- Example:
[grid content="page" date_query_after="30 days ago"]
date_query_before
- Type: string
- Description: Get posts published before a date. Use any value strtotime() accepts.
- Example:
[grid content="post" date_query_before="11 April 2018"]
entry_class
- Type: string
- Description: HTML class
- Example:
[grid content="post" entry_class="custom-class another-class"]
exclude
- Type: string
- Description: Exclude specific posts or taxonomy terms by ID. Accepts a comma-separated list of post IDs.
- Example:
[grid content="post" exclude="14, 1045, 99"]
[grid content="category" exclude="22, 948, 461"]
exclude_categories
- Type: integer(s), comma separated
- Description: Exclude posts from specific categories. Accepts a comma-separated list of category IDs.
- Example:
[grid content="post" exclude_categories="12, 56"]
exclude_current
- Type: boolean
- Default: false
- Description: Exclude the current post. This is useful when displaying recent posts on a single post page. When true, the grid will not show the post you are currently viewing.
- Example:
[grid content="post" exclude_current="true"]
exclude_displayed
- Type: boolean
- Default: false
- Description: Only show posts that haven’t already been shown in other instances of [grid] on page/post.
- Example:
[grid content="post" exclude_displayed="true"]
grid_title_class
- Type: string
- Description: Add additional HTML classes to the grid title.
- Example:
[grid content="post" grid_title_class="grid-title another-class"]
grid_title_wrap
- Type: string
- Default: h2
- Description: Configure the title HTML wrap.
- Example:
[grid content="post" grid_title_wrap="h3"]
gutter
- Type: integer
- Default: md
- Description: Space between columns, in pixels. Accepts the values of “xxxs”, “xxs”, “xs”, “sm”, “md”, “lg”, “xl”, “xxl”.
- Example:
[grid content="post" gutter="lg"]
hide_empty
- Type: boolean
- Default: true
- Description: Hide terms with no content. Only a valid parameter when displaying taxonomy terms (when “content” parameter is set to a taxonomy name).
- Example:
[grid content="category" hide_empty="false"]
id
- Type: string
- Description: Add an HTML id to the main grid HTML.
- Example:
[grid content="post" id="home-recipes"]
ignore_sticky_posts
- Type: boolean
- Default: true
- Description: Exclude sticky posts.
- Example:
[grid content="post" ignore_sticky_posts="true"]
image_align
- Type: string
- Description: Align an entry image to the left, right, or centered. Accepts left, right, or center.
- Example:
[grid content="post" image_align="right"]
image_location
- Type: string
- Default: before_entry
- Description: Configure the image display location. Note: the “show” parameter must have “image” as one of it’s values (this is the default). If the “show” parameter doesn’t have “meta” as a value, after_title and before_content will look the same. Accepts “bg” (background image), “before_entry”, “before_title”, “after_title”, and “before_content”
- Example:
[grid content="post" image_location="bg"]
image_size
- Type: string
- Default: one-third
- Description: Configure the image size to be used. Note: the “show” parameter must have “image” as it’s value (this is the default). View all Mai Theme image sizes or view WooCommerce image sizes.
- Example:
[grid content="post" image_size="one-half"]
link
- Type: boolean
- Default: true
- Description: Link grid content to original content. You may want to show a grid of content that doesn’t link to the original post/term. This may be useful for displaying testimonials or similar.
- Example:
[grid content="post" link="false"]
meta_key
- Type: string
- Description: Display content with a specific meta data key/value.
- Example:
[grid content="post" meta_key="color" meta_value="red"]
meta_value
- Type: string
- Description: Display content with a specific meta data key/value.
- Example:
[grid content="post" meta_key="color" meta_value="red"]
more_link_text
- Type: string
- Default: Read More
- Description: Customize the “Read More” link text.
- Example:
[grid content="post" more_link_text="View More"]
no_content_message
- Type: string
- Default: Sorry, no content matched your criteria.
- Description: Define a message to display with posts that have no content.
- Example:
[grid content="post" no_content_message="Uh oh! There is nothing to see here!"]
offset
- Type: integer
- Default: 0
- Description: The number of posts to skip in the query before display. Useful when using multiple instances of [grid] to show sequential posts with different layouts/columns per-instance.
- Example:
[grid content="post" offset="2"]
overlay
- Type: string
- Default: “dark” if image_location=”bg”, otherwise null.
- Description: The style of overlay, if any, to add on an entry. Typically used when image_location=”bg”. Accepts “gradient”, “light”, “dark”.
- Example:
[grid content="post" overlay="gradient"]
rel
- Type: string
- Description: Set the entry link rel attribute.
- Example:
[grid content="post" target="_blank" rel="noopener"]
row_class
- Type: string
- Description: HTML class applied to the row wrap.
- Example:
[grid content="post" row_class="some-class"]
status
- Type: string
- Default: “publish” (or “publish, private” if user is logged in).
- Description: Display posts with specific post status.
- Example:
[grid content="post" status="private"]
tags
- Type: string
- Description: Display posts containing defined tags. Accepts a comma-separated list of tag IDs.
- Example:
[grid content="post" tags="144, 213"]
target
- Type: string
- Description: Set the entry link
target
attribute. - Example:
[grid content="post" target="_blank" rel="noopener"]
tax_field
- Type: string
- Default: term_id
- Description: Change the taxonomy field to use with “terms” parameter (via WP_Query).
- Example:
[grid content="post" taxonomy="category" tax_field="slug" terms="recipes"]
tax_include_children
- Type: boolean
- Default: true
- Description: Whether or not to include children for hierarchical taxonomies (via WP_Query).
- Example:
[grid content="post" categories="123" tax_include_children="false"]
tax_operator
- Type: string
- Default: IN
- Description: Operator to test. Possible values are IN , NOT IN , AND , EXISTS and NOT EXISTS .
- Example:
[grid content="product" taxonomy="product_cat" terms="1562"] tax_operator="NOT IN"]
taxonomy
- Type: string
- Description: Taxonomy to use in “tax_query” (via WP_Query). Used with “terms” parameter.
- Example:
[grid content="post" taxonomy="animal" terms="123"]
terms
- Type: string
- Description: Terms in a taxonomy or list of taxonomies (via WP_Query). Accepts a comma-separated list of category IDs, unless tax_field is ‘slug’, then comma separated list of slugs. Used with “taxonomy” parameter.
- Example:
[grid content="post" taxonomy="category" terms="122, 134"]
title_wrap
- Type: string
- Default: h3
- Description: Configure the title HTML wrapping element.
- Example:
[grid content="post" title_wrap="h3"]
top
- Type: integer
- Default: null
- Description: The amount of top margin/spacing on each grid entry. Accepts “none”, “xxxs”, “xxs”, “xs”, “sm”, “md”, “lg”, “xl”, or “xxl”
- Example:
[grid content="post" top="lg"]
SLIDER PARAMETERS*
*Require slider="true"
in your [grid]
adaptiveheight
- Type: boolean
- Default: false
- Description: Allow the grid height to shrink/grow depending on each slide’s content. Only works when
columns="1"
. Ignoresalign_cols
parameter. Only allowsalign_text
to beleft
,center
, orright
. - Example:
[grid content="post" columns="1" slider="true" adaptiveheight="true"]
arrows
- Type: boolean
- Default: true
- Description: Display slider navigation arrows.
- Example:
[grid content="post" slider="true" arrows="false"]
autoplay
- Type: boolean
- Default: false
- Description: Whether to autoplay the slider.
- Example:
[grid content="post" slider="true" autoplay="true"]
center_mode
- Type: boolean
- Default: false
- Description: Mobile “peek”.
- Example:
[grid content="post" slider="true" center_mode="true"]
dots
- Type: boolean
- Default: false
- Description: Display navigation dots below the slider.
- Example:
[grid content="post" slider="true" dots="true"]
fade
- Type: boolean
- Default: false
- Description: Fade in the next slide. Please note, fade only works with 1 column.
columns="1"
- Example:
[grid content="post" columns="1" slider="true" fade="true"]
infinite
- Type: boolean
- Default: true
- Description: Loop slider from the last post/item back to the first.
- Example:
[grid content="post" slider="true" infinite="false"]
slidestoscroll
- Type: integer
- Default: Defaults to the amount of columns
- Description: The number of slides/posts to advance in slider.
- Example:
[grid content="post" slider="true" slidestoscroll="2"]
speed
- Type: integer
- Default: 3000
- Description: Autoplay Speed in milliseconds.
- Example:
[grid content="post" slider="true" speed="2000"]
FACETWP PARAMETERS*
*Requires the FacetWP plugin (not-included).
facetwp
- Type: boolean
- Default: false
- Description: Allow the grid content to be filterable via
- Example:
[grid content="product" number="all" facetwp="true"]
WOOCOMMERCE PARAMETERS*
*Requires the WooCommerce plugin (not-included).
*Requires content="product"
in your [grid]
show
- Type: string
- Description: Accepts a comma-separated list of values that only apply to Woocommerce products. Woo-only parameters are “add_to_cart” and “price”.
- Example:
[grid content="product" show="image, title, add_to_cart, price"]
RESPONSIVE BREAKPOINT PARAMETERS
These are very complex and typically won’t be needed by normal users. Proceed with caution. 😉
The following parameters can be used to set the span of each column out of 12 total imaginary columns on the page. If you set a breakpoint parameter to “6” that would display in 2 columns (or 1/2), since 6 is 1/2 of 12. To display 3 columns you would us “4” since 4 out of 12 is 3, or 1/3.
I told you it was confusing 😉
xs
- Type: string
- Description: Set the span each entry should use out of 12 columns per row on extra small size devices/screens.
- Example: [grid content=”post” xs=”12″]
sm
- Type: string
- Description: Set the span each entry should use out of 12 columns per row on small size devices/screens.
- Example: [grid content=”post” xs=”12″ sm=”6″]
md
- Type: string
- Description: Set the span each entry should use out of 12 columns per row on medium size devices/screens.
- Example: [grid content=”post” xs=”12″ sm=”6″ md=”4″]
lg
- Type: string
- Description: Set the span each entry should use out of 12 columns per row on large size devices/screens.
- Example: [grid content=”post” xs=”12″ sm=”6″ md=”4″ lg=”3″]
xl
- Type: string
- Description: Set the span each entry should use out of 12 columns per row on extra large size devices/screens.
- Example: [grid content=”post” xs=”12″ sm=”6″ md=”4″ lg=”3″ xl=”2″]
USAGE EXAMPLES
Example 1
In its simplest use, use the Grid shortcode to display all your posts in a grid that will display all posts with their featured image and title, like this:
[grid content="post" number="6"]
To display pages instead of posts, use
[grid content="page" number="6"]
Example 2 – Display titles over featured image
To displays the 3 most recent posts, center-aligned within the page, with horizontally and vertically centered content, showing the post’s title and featured image as a background, use the shortcode like this:
[grid content="post" number="3" image_location="bg" align_text="center, middle"]
Let’s take a look at what that all means:
It all looks like this:
Example 3 – Display title, excerpt, and read more link
The show parameter is used to display the content, excerpt, image, more_link (as a Read More button), title, author, date and taxonomies. This example uses Grid with 4 show values – image, title, excerpt and more_link – an excellent layout for any blog.
[grid columns="3" show="image, title, excerpt, more_link"]
It looks like this.
Example 4 – Display child pages
Grid is a true powerhouse when it comes to site architecture. Use it to display child pages of a parent on any page, including the parent page. Used this way, Grid is a great alternative to traditional sub-page menus.
[grid content="page" parent="current" order="ASC" order_by="menu_order" columns="2"]
It looks like this.
Example 5 – Display WooCommerce Products
[grid content="product" columns="3" number="6" show="image, title, price, add_to_cart" ali