Webflow Tips

Best practices for using SwiperFlow in Webflow projects.

Adding the Script

Go to Project Settings → Custom Code and add the SwiperFlow script before the closing </body> tag:

<script src="https://cdn.jsdelivr.net/npm/@jamesbattye-dev/swiperflow@latest/dist/index.js"></script>

For specific versions:

<script src="https://cdn.jsdelivr.net/npm/@jamesbattye-dev/swiperflow@0.0.2/dist/index.js"></script>

Adding Custom Attributes

In Webflow, add custom attributes through the element settings:

Select the element in the Designer
Go to Element Settings (gear icon) or right-click → Settings
Scroll to Custom Attributes
Click + to add a new attribute
Enter the attribute name (e.g., data-swf-component) and value

Attribute Tips

Name: Enter the full attribute name including data-swf-
Value: Enter the value, or leave empty for boolean attributes
For boolean attributes like data-swf-loop, you can set value to true or leave it empty

Building the Structure

Step 1: Create the Container

Add a Div Block
Add custom attribute: data-swf-component with a unique identifier value (e.g., my-slider)
This identifier is required and used for JavaScript API access

Step 2: Create the Wrapper

Inside the container, add another Div Block
Add custom attribute: data-swf-element with value wrapper

Step 3: Create the List

Inside the wrapper, add a Div Block
Add custom attribute: data-swf-element with value list
Add your configuration attributes here (e.g., data-swf-loop with value true)

Step 4: Create Slide Items

Inside the list, add Div Blocks for each slide
Add custom attribute: data-swf-element with value item
Style these however you like

Using CMS Collections

SwiperFlow works great with Webflow CMS:

Create a Collection List inside your data-swf-element="list" element
On the Collection Item, add data-swf-element with value item
Design your collection item as needed

The slider will automatically include all CMS items as slides.

Inside the component (but outside the wrapper), add a Div Block
Add attribute: data-swf-element with value navigation
Inside, add two elements (buttons, divs, links, etc.)
On the first, add data-swf-element with value prev-arrow
On the second, add data-swf-element with value next-arrow

Pagination Dots

Inside the component (but outside the wrapper), add a Div Block
Add attribute: data-swf-element with value pagination
Inside, add a single element (button or div)
Add attribute: data-swf-element with value pagination-dot
Style this element — SwiperFlow will clone it for each slide

Styling Active States

Active Slide

The active slide receives the class swiper-slide-active by default. To use a custom class:

Add attribute data-swf-active-class with your preferred class name
Create that class in Webflow and style it

Active Pagination Dot

Active pagination dots receive the is-active class. In Webflow:

On your pagination dot element, add a combo class called is-active
Style the active state (e.g., different background color, scale)

Responsive Behavior

Mobile-Only Slider

To show content as a grid on desktop but a slider on mobile:

Add data-swf-init with value mobile to your list element
Use Webflow's responsive settings to style the grid layout on desktop
The slider will only initialize on mobile viewports

Different Slides Per View

Use breakpoint attributes on the list element:

data-swf-bp-desktop — Slides on desktop (≥992px)
data-swf-bp-tablet — Slides on tablet (569-991px)
data-swf-bp-mobile — Slides on mobile (320-568px)

Common Webflow Patterns

Full-Width Hero Slider

Section (100vw width, overflow hidden)
└── data-swf-component="hero" (position relative)
    └── data-swf-element="wrapper" (overflow visible)
        └── data-swf-element="list"
            └── data-swf-element="item" (100% width)

Centered Card Carousel

Section
└── Container
    └── data-swf-component="cards"
        └── data-swf-element="wrapper" (overflow visible for effects)
            └── data-swf-element="list" (data-swf-centered="true")
                └── data-swf-element="item"

Product Grid Slider

Section
└── Container
    └── data-swf-component="products"
        └── data-swf-element="wrapper"
            └── data-swf-element="list" (with bp-desktop, bp-tablet, bp-mobile)
                └── Collection List
                    └── Collection Item (data-swf-element="item")

Troubleshooting

Slider Not Initializing

Check that the script is loading (check browser console)
Verify all required elements have correct attributes
Make sure attribute names are exactly data-swf-component, data-swf-element, etc.
Check for typos in attribute values

Slides Not Showing

Ensure slides have content and dimensions
Check that the wrapper has overflow: hidden or overflow: visible as needed
Verify the list element contains the slide items

Both prev-arrow and next-arrow must be present
They must be inside a navigation element
The navigation element must be inside the component

Pagination Not Showing

The pagination-dot template must be inside the pagination element
The pagination element must be inside the component
Style the dot element so it's visible

Styles Conflicting

SwiperFlow uses your existing Webflow classes
Avoid using Swiper's default class names unless intentional
Use custom data-swf-active-class if you have conflicts

Performance Tips

Use WebP images for slides
Lazy load images outside the initial viewport
Avoid too many slides in loop mode (causes extra DOM clones)
Consider using data-swf-init to only load sliders when needed

Interactions

SwiperFlow doesn't conflict with Webflow Interactions. You can:

Trigger interactions on slide change using JavaScript events
Animate elements within slides using Webflow's scroll animations
Combine with hover states on navigation elements

Example using the API:

window.swiperflow.on('swfLoaded', ({ sliders }) => {
  sliders.forEach(slider => {
    slider.getSwiperInstance.on('slideChange', () => {
      // Trigger Webflow interactions or custom animations
    });
  });
});