How To Use The Repeater Element in Oxygen Builder [Beginners Guide – Article]

Welcome back to another Oxygen Builder tutorial. In this post, you’ll learn how to use the repeater element in Oxygen to create looped content by using a post query. Let’s dive right in.

The repeater element is one of Oxygen’s powerful components. In its basic form, the repeater element consists of a single div as the child element. You can create layouts for displaying blog posts and customize exactly what to display using a post query.

Step One

For this tutorial, you can create a simple re-usable part in Oxygen by navigating to Oxygen > Templates and click on Add New Reusable Part.

Give the re-usable part a name, something like ‘test reusable part’. Unless you’re creating something very specific, such as a ‘blog archives element’.

Next, click on publish to activate your new reusable part and then click on Edit With Oxygen.

Step Two

Once inside the Oxygen Editor, head over to add element and drop in a new section followed by the repeater element. See the image below.

As I mentioned, in its simplicity, the repeater element consists of a single div as the child element. Let’s select the repeater in the structure panel and head over to Primary Tab in the right column.

Here we have several options.

1. Query
2. Layout
3. Pagination
4. Grid Layout

Let’s start with Query (click on Query) since this is at the heart of the repeater’s features.

💡 The WP_Query is a core class in WordPress used to query or retrieve posts from the WordPress database based on a variety of parameters.

The default is the regular setting and is most commonly used for something very simple. But we can also choose custom, manual, and advanced. We’ll dive deeper into each one. See the image below.

Custom Query

Custom is also a frequently used query option, because it allows you to control a number of parameters as outlined below –

1. Post type – Here you can select post or page. You can also manually specify the IDs of posts and pages. IDs are ideal if you want to create a repeater to display specific posts or pages. For example, perhaps you’re building a featured content section for your homepage and want to select specific pages to display in the featured section.
2. Filtering – Under filtering, you can display posts or pages to appear in a specific category, tag, WooCommerce product category, tags, and filter by author.
3. Order – Under the order, you can display posts or pages by date, date last modified, title, comment, count, menu order, and more.
4. Count – Under the count option, you can select how many posts or pages you want to have displayed in the repeater and whether you’d like to ignore sticky posts.

The Custom Query option can be a lot of fun and powerful, so have fun experimenting.

Manual Query

Manual allows you to add query parameters in manually. It requires a little bit of knowledge in WordPress Query Params. The default is what you see in the Query params field and is set to: display posts by author admin, category is uncategrized, and number of posts per page is set to two.

Advanced

Advanced Query is for more advanced users and WordPress Developers. That said, there are some presets built in that you can use.

The query editor, again an advanced feature, lets you build custom queries from scratch rather than use one of the presets. If you have experience working with WordPress queries you can really make the most of the advanced query option. We’ll be adding more tutorials on using the advanced query builder in Oxygen at a later time.

There is a valuable resource article on Bill Ericson’s website where he has conveniently displayed all of the arguments that wp_query accepts. Check it out here.

OK, let’s go back to the repeater’s primary opions.

Layout

Next up we have the layout options.

Here we can set the layout of our repeater element content. In most cases, you would leave this to vertical. However, on occasions that you might use horizontal would be if you’re trying to create a table using the repeater component.

Note: If you are e member of Van Marciano Pro, don’t forget to log in to check out our collection design video tutorials using the repeater element.

Pagination

If you’re trying to create a post archive template using the repeater element, the pagination options let you customize the function, look, and style of the pagination.

Grid Layout

The grid layout option lets you specify the number of columns you would like to use in the repeater, as well as set widths, alignments, rows, etc.

Preview Render

This option is useful if you need to boost the performance of your page. You don’t always need to preview all of the items in the repeater. Enabling single mode will only render the div you’re working on.

Summary

So there you have it. A quick and dirty beginners guide to using the repeater element and an introduction to wp_query. Hope you found it useful. I cover using the repeater element in more depth complete with video tutorials in my Oxygen Builder Visual Design Mastery Course here.