Carousel Builder

This component allows you to build dynamic carousels in Oxygen. The carousels can be for a wide range of uses, testimonial sliders, featured posts & pages, supporting the Repeater component, Easy Posts, Product Lists, Related Products or building your own carousel with cells made of any elements.

Here are some short teaser videos showing some of the functionality with building custom carousels in Oxygen..

In-Editor Mode

There are two main working ‘modes’ when working with the carousel builder inside of Oxygen itself; ‘Preview’ and ‘Edit’. With some settings, the changes will only be visible when inside Oxygen depending on which mode you are in.

Edit Mode

Edit mode is the default mode to build your carousel and where you’ll find yourself most of the time. In edit mode all elements inside the carousel builder are completely editable, so you are free to add elements, style elements using the UI, and build freely like you would build anything else in Oxygen.

Preview Mode

Preview mode allows you to preview what the final design will look like from inside the builder as the carousel initializes and becomes functional. Clicking on the carousel while in preview mode will move the carousel to the next cell. You can also navigate forwards and backward using the navigation elements if you are using them in your carousel.

Important – do not attempt to drag the carousel while inside Oxygen as you’ll be dragging the elements to reposition them.

The settings available in preview mode are mainly for controlling how the carousel behaves, for eg how many cells to move at once (grouping cells), changing the cell alignments & setting the friction & drag for the user interaction with the carousel.

Preview mode is not for making changes to the cell widths, heights, or for repositioning or styling elements inside the repeater. In preview mode the elements inside the repeater are non-selectable and some of the layout controls will be hidden. To make changes such as these, head back into edit mode.

Note – The quickest way to see the recommended workflow is to watch this video showing a testimonial carousel being built from start to finish in five minutes.

For advanced users – we are using Flickity to power the carousel builder. If you already have some experience with Flickity and a few of the options, you likely won’t need to read this documentation as it all should be pretty intuitive from exploring the controls.

Building a Carousel – Workflow

The first step after adding a new carousel builder to the page is to choose the element inside which will act as the container for the carousel. Supported components are the Repeater, Easy Posts, Woo components such as Product List, Category List, Related Products, Product Upsells.

You can also choose to add elements manually using the ‘custom elements’ option in the dropdown. Here you will just need to give the elements the class ‘cell’ to make sure they are used as the cells inside the carousel.

If using the Repeater component or the Easy Posts component, the next step would be to set the repeater query to get whichever dynamic data you want and then start adding in your elements and style the individual cell. At this stage, you’d just be focused on building/styling one individual cell (no different from the usual workflow with the repeater) and not on the overall layout of the carousel itself.

Depending on which components you are adding to build the carousel, different settings may appear in the ‘Other’ tab. For eg if creating a Woocommerce carousel, there are some additional options to hide some of the elements you may not need to visible inside a carousel such as the buy buttons, the price, the results count, the sorting dropdown, etc.

Carousel Layout

When it comes to the layout of the carousel itself, which includes choosing the height and width of the cells inside – instead of changing any of this inside the repeater, this can all done from the inside the carousel builder’s primary controls.

This means that you won’t need to keep going back inside the repeater unless you need to make specific style changes to elements or add more elements, for everything else you can do it from the carousel builder.

Cells Tab

From inside the cells tab, the width and heights of each cell can be changed across different screen sizes by using Oxygen’s responsive dropdown menu. The widths are in percentages by default, this allows you to easily choose how much of each cell will be visible at each different viewport width.

The space between setting will add margin in between the cells.

The selected cells and prev/next cell tabs allow you to add some styles to the repeater div conditionally. These styles will only be applied when it is either the currently selected cell or the one previous or the one next. If you are grouping cells (meaning more than one cell will be selected at one time) then the styles will apply to the whole group.

Pro Tip – dynamic classes are added to the cells only when they are selected or are adjacent to the currently selected cell. The classes that are added are..

  • is-selected
  • is-previous
  • is-next

This means you are not limited to the style controls that are built-in. You can add custom selectors in Oxygen to target any specific elements that you have added inside your carousel only when they are inside a selected cell.

For eg, you could add in a button that you want to be hidden in each cell apart from the currently selected one. The way to do this would be to give the button a class, say ‘my-revealing-button’ then hide your button by setting the opacity to 0 and visibility to hidden. To make it be revealed in the selected cell, you can add a custom selector by going to Manage > Selectors > Add Selector and then creating a selector ‘.is-selected .my-revealing-button’. Once this is done you can set this selector to have the opacity at 1 and the visibility back to visible.

That’s it. These dynamic classes mean you can make pretty much any style change as different cells are selected by the user. So you can create some very unique designs.

Cell selector – You change the cell selector from the default ct-div-block (which is the just the div inside the repeater.) The only reason you’d likely need to change this is if you are adding multiple divs inside the repeater. In this case, you will need to give the main repeater div a new class to differentiate it from the other divs inside.

Carousel Tab

This tab is where you’ll find most settings for the behavior of the carousel. These settings will only be visible inside Oxygen if in preview mode.

Group Cells – Multiple cells can be grouped together to move as one object when using the navigation arrows or pagination dots.

Initial cell selected – Here you can choose which cell to be selected when the page first loads.

Cell Align – Align cells within the carousel.

Overflow – Choose whether the carousel overflows the container in the x-axis.

Adaptive Height – If enabled the entire carousel will change the height to match the height of the selected cell. You also have the option to change the transition of the height change for a smoother effect.

Wrap around – At the end of cells, wrap-around will add cells to the other end for infinite scrolling.

Ticker (continuous play) – If wrap around is enabled, there is also an option to have the cells continuously play at a set speed. Useful for logo tickers. Note that it’s best to remove the navigation arrows if this feature is active.

Contain – Contains cells to carousel element to prevent excess scroll at the beginning or end.

Click cell to select – Allows users to browse through the carousel by clicking on cells to select them instead of just dragging.

Autoplay – Automatically advances to the next cell at an interval set in ms. Leaving at zero disables autoplay.

Carousel is draggable – Enables dragging and flicking. On by default.

Free Scrolling – Enables content to be freely scrolled and flicked without aligning cells to an end position.

Autoplay – Automatically advances to the next cell at an interval set in ms. Leaving at zero disables autoplay.

Use as Navigation – Use one carousel as navigation for another. Enter the selector of the other carousel builder. (It’s best to also enable ‘click cell to select’, this way clicking on each cell in this carousel will be the controller for browsing across a second carousel). Both carousels will now be connected which means if the user manually drags the other carousel, this carousel will also move.

Percentage Position – Sets positioning in percent values, rather than pixel values. This is enabled by default and should only be disabled if you’re setting px values for your cells.

Keyboard Navigation – Enable keyboard navigation. Users can tab to a Flickity carousel, and pressing left & right keys to change cells.

Right to Left – Enables right-to-left layout for the carousel.


Any elements inside the repeater can be set to run at slightly different speeds when the carousel is moving, allowing you to create your own parallax effect to add some depth to the carousel.

In the ‘other’ tab the parallax setting is found (only if the Repeater used). Once this feature is enabled, to change the speed of an inner element we’re making use of Oxygen’s custom attributes feature found at Advanced > Attributes.

To set the speed, enter ‘data-speed’ as the attribute name and the value as an integer. Where 1 is completely fixed and the effect is more subtle the higher the number. 20 will give a much more subtle effect.

Navigation Arrows

The built-in icons will be suitable for most use cases. The icons can be changed to any custom icons. They are positioned relative to the carousel to sit center aligned on either side. All the style controls found underneath apply to these built in icons.

If you choose the ‘use custom elements’ instead of using the preset icons, you can then choose any elements on the page to function as either the previous or next navigation buttons for the carousel. These elements don’t need to be inside of the carousel builder, they can be anywhere on the page. None of the style controls will apply to your custom elements, you would instead style use the style controls on the elements that you are using.

Choosing ‘none’ will simply remove the navigation completely from the carousel.

Page Dots

The page dots can be styled, repositioned or not output at all.

If you’re wishing to use page dots on desktop, but remove from mobiles where there may not be enough room, you can select the breakpoint where you want to hide the dots below from the dropdown.

Friction / Drag

The controls are the only controls where the results cannot be seen inside Oxygen, no matter which mode you are in. This is because it controls the dragging motion, something that cannot be done from inside the builder.

Drag Threshold – Choose the number of px that the user needs to drag before the carousel will be moved. (useful to prevent accidental dragging)

Selected Attraction – Attracts the position of the slider to the selected cell. Higher attraction makes the slider move faster. Lower makes it move slower

Friction – Slows the movement of the carousel. Higher friction makes the carousel feel stickier and less bouncy. Lower friction makes the slider feel looser and more wobbly.

Free Scroll Friction – Only available if free-scrolling is enabled. Higher friction makes the slider feel stickier. Lower friction makes the slider feel looser

Some Pro Tips

  • We recommend working primarily in edit mode so you have access to the most settings while inside the builder. Preview mode is designed to be used sparsely to ‘preview’ how the carousel will look on the front end, not as the default mode for building. Some settings such as the cell dimensions are hidden in preview mode to prevent errors & confusion.
  • Turning off/on some settings will conditionally show/hide other settings. This is to ensure you are only seeing the settings that apply to the type of carousel you are building. eg if you turn on Wrap Around then the Contain setting will be hidden as this wouldn’t have any effect for a carousel with infinite cells.
  • To avoid FOUC as the page loads as much as possible, make sure to set a height on the cells as well as the width. This will prevent the entire layout moving such as the navigation, the dots, and any content underneath as the carousel is built.
  • Although AOS scroll animations won’t be able to be added to the carousel builder itself, they can be added to all elements inside. Adding a fade effect on the repeater is another easy way to hide the images etc loading from inside the carousel.