Use Swiper Breakpoints for Responsive slidesPerView Without Media Queries

The problem: one slide count does not fit every screen

You initialize Swiper with slidesPerView: 4 and spaceBetween: 24. On a desktop monitor the carousel looks right. On a phone, four slides are squeezed into a narrow viewport, text becomes unreadable, and touch targets overlap. You could write CSS media queries to hide slides or adjust widths, but that duplicates layout logic outside the Swiper instance and can drift from the component’s own sizing calculations.

The useful takeaway: Swiper breakpoints let you override slidesPerView, spaceBetween, and other parameters at defined viewport widths, keeping responsive behavior inside the instance configuration. This guidance assumes Swiper 6.x or 7.x; version 4.x uses different breakpoint syntax and lacks some deep-merge behavior.

How breakpoints match viewport widths

Breakpoint keys are numbers interpreted in pixels, not CSS media query strings. Swiper selects the largest key that is less than or equal to the current window width and merges those parameters over your base configuration. If the window is 800 pixels wide and you define breakpoints at 640 and 1024, Swiper applies the 640 values. If the window is 1200 pixels wide, it applies the 1024 values.

Because the merge is deep, supplying only slidesPerView at a breakpoint preserves other base settings such as spaceBetween unless you explicitly override them. Supplying a partial object for a nested option like grid can replace rather than append to the base value, so test nested options carefully after a breakpoint change.

Worked example: mobile, tablet, desktop slide counts

This configuration starts with one slide on small screens, shows two at 640 pixels, and four at 1024 pixels.

import Swiper from 'swiper';
import 'swiper/css';

// Run in your page script or module bundle after the DOM is ready.
// No special permissions are required.
new Swiper('.product-carousel', {
  slidesPerView: 1,
  spaceBetween: 16,
  breakpoints: {
    640: {
      slidesPerView: 2,
      spaceBetween: 20,
    },
    1024: {
      slidesPerView: 4,
      spaceBetween: 24,
    },
  },
});

Replace .product-carousel with your container selector. Placeholders such as 640 and 1024 are viewport widths in pixels; adjust them to your design breakpoints.

What to expect at each width

Window width	Active breakpoint	slidesPerView	spaceBetween
Below 640 px	Base config	1	16 px
640 px to 1023 px	640	2	20 px
1024 px and above	1024	4	24 px

Limitations and failure modes

• Keys are not media queries. Do not write '(min-width: 640px)' as a breakpoint key. Swiper expects a number.
• Deep merge can hide overrides. If you set grid: { rows: 2 } in the base config and grid: { rows: 1 } at a breakpoint, the nested object may replace the base grid settings entirely rather than merging only rows. Verify nested options after a breakpoint change.
• Breakpoints are read primarily at initialization and on resize. Changing the breakpoints object after initialization does not take effect automatically. You must call swiper.destroy() and re-initialize, or call swiper.update() after changing parameters through the API.
• Rapid resize events can cause recalculation. If you observe layout thrashing while dragging the browser edge, avoid adding extra resize listeners and let Swiper’s built-in resize handling manage it.
• Version differences. Swiper 4.x used a different breakpoint structure. Check your installed major version before copying examples from older tutorials.

Verify the result

1. Open the page in a browser and open DevTools.
2. Resize the viewport below 640 pixels. Inspect a .swiper-slide element and check its computed width. It should approximately match the container width adjusted for the base spaceBetween.
3. Resize above 640 pixels. The slide width should shrink so that two slides fit, and the gap between slides should reflect 20 pixels.
4. Resize above 1024 pixels. Four slides should fit, with 24 pixels between them.
5. If the layout does not change, confirm you are using Swiper 6.x or 7.x and that the breakpoint keys are numeric, not strings.

There is no built-in public property that names the active breakpoint in every version, so verifying rendered slide widths and gaps in DevTools is the most reliable practical check.

When to use breakpoints instead of CSS

Use Swiper breakpoints when the responsive behavior is tied to the carousel’s own layout logic—slide count, spacing, and grid rows. Use CSS media queries for unrelated page layout, such as hiding the carousel entirely on small screens or changing surrounding typography. Keeping carousel dimensions inside Swiper reduces the chance that CSS overrides conflict with Swiper’s calculated slide widths and transforms.

Start with the smallest sensible base configuration, add breakpoints only where the design actually changes, and verify each threshold in DevTools before shipping.