PHPackages                             codey/swiper-block - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. codey/swiper-block

ActiveKirby-plugin[Utility & Helpers](/categories/utility)

codey/swiper-block
==================

Kirby CMS layout block plugin — Swiper 12 slider with panel editor and image cropping

v1.0.2(1mo ago)13↑2900%MITPHPPHP >=8.3CI failing

Since Jun 5Pushed 1mo agoCompare

[ Source](https://github.com/ianhobbs/swiper-block)[ Packagist](https://packagist.org/packages/codey/swiper-block)[ RSS](/packages/codey-swiper-block/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (4)Used By (0)

[![Packagist Version](https://camo.githubusercontent.com/702d8d3ac2641fef969f65bd8418b53dcf5dbe1e2bc2c9d97746fc3da746c870/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69616e686f6262732f6b697262792d7377697065722d626c6f636b)](https://camo.githubusercontent.com/702d8d3ac2641fef969f65bd8418b53dcf5dbe1e2bc2c9d97746fc3da746c870/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69616e686f6262732f6b697262792d7377697065722d626c6f636b)[![Kirby 4+](https://camo.githubusercontent.com/be8a318b21034e32192161140f59f34728438ae2ba819ac02e4d44079dc6929b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4b697262792d342532422d626c61636b)](https://camo.githubusercontent.com/be8a318b21034e32192161140f59f34728438ae2ba819ac02e4d44079dc6929b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4b697262792d342532422d626c61636b)[![License MIT](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)

Kirby Swiper Block
==================

[](#kirby-swiper-block)

A Kirby CMS layout block plugin that renders a full-featured [Swiper 12](https://swiperjs.com/) slider with a Panel editor, responsive image cropping, lazy loading, and LQIP blur-up placeholders.

Swiper is loaded via CDN — no npm or build step required to use the plugin.

**Requires:** Kirby 4 or 5 · PHP 8.1+

---

Installation
------------

[](#installation)

### Via Composer (recommended)

[](#via-composer-recommended)

```
composer require ianhobbs/kirby-swiper-block
```

### Manual

[](#manual)

Clone into your site's `site/plugins/` directory:

```
git clone https://github.com/ianhobbs/swiper-block site/plugins/swiper-block
```

---

Zero-config setup
-----------------

[](#zero-config-setup)

No template changes needed. When a page contains a Swiper block, the snippet automatically injects the Swiper CDN scripts and plugin CSS **once per page load** using a static flag. Everything is self-contained.

If you prefer to control asset placement (e.g. move them to `` for performance), add these lines to your layout template and set `SWIPER_ASSETS_LOADED` in your config — see [Manual asset loading](#manual-asset-loading) below.

---

Usage in the Panel
------------------

[](#usage-in-the-panel)

Add the `swiper` block type to any blocks or layout field in your blueprint:

```
fields:
  content:
    type: blocks
    fieldsets:
      - swiper
```

The block editor opens with **5 tabs** covering all configuration options:

### Tab 1 — Slides (per-slide settings)

[](#tab-1--slides-per-slide-settings)

FieldDescriptionImageSingle image — min. 1920 × 810 px recommendedHeadingSlide titleSubtext / CaptionOptional body textCTA Link + LabelOptional call-to-action buttonContent PositionLeft / Centre / Right### Tab 2 — Layout

[](#tab-2--layout)

FieldDefaultDescriptionAspect Ratio16:921:9 / 16:9 / 4:3 / 1:1 / Custom heightCustom Height600 pxFixed height in px (when Aspect Ratio = Custom)Slide DirectionHorizontalScroll direction — Horizontal or VerticalOrientationHorizontalImage crop set — Horizontal (16:9 → `swiper-horiz`) or Vertical (9:16 → `swiper-vert`)Slides Visible11 / 2 / 3 / 4 / AutoAdvance Per Click1Slides to jump per navigation actionGap Between Slides0 pxSpacing between slidesCentre Active SlideOffKeeps the active slide centredStarting Slide0Zero-based index of the first visible slide### Tab 3 — Animation

[](#tab-3--animation)

FieldDefaultDescriptionTransition EffectSlideSlide / Fade / Creative (zoom) / CoverflowTransition Speed600 ms100–3000 msLoopOnInfinite loopAutoplayOffAuto-advances slidesAutoplay Delay4000 msDelay between slides (when Autoplay is On)Pause on HoverOnPauses autoplay on mouse enter (when Autoplay is On)Free ModeOffSlides move freely without snappingFree Mode MomentumOnMomentum-based deceleration (when Free Mode is On)### Tab 4 — Controls

[](#tab-4--controls)

FieldDefaultDescriptionArrow ButtonsVisiblePrevious / Next navigation arrowsPaginationVisiblePagination indicatorPagination StyleBulletsBullets / Fraction (2/5) / Progress BarDynamic BulletsOnActive bullet enlarges relative to neighboursKeyboard NavigationOnArrow keys navigate slides when in viewportMousewheel ControlOffScroll wheel advances slides### Tab 5 — Touch & Input

[](#tab-5--touch--input)

FieldDefaultDescriptionGrab CursorOnShows a hand cursor when dragging on desktopTouch on DesktopOnAllows mouse drag to simulate touchSwipe Threshold5 pxMinimum drag distance to register a swipeLong SwipesOnLong swipe gestures advance the sliderEdge ResistanceOnDrag resistance at the first and last slide---

Image presets (required config)
-------------------------------

[](#image-presets-required-config)

The snippet serves responsive images with Kirby's native `srcset()`, generating **webp** crops in two orientations. Because Kirby plugins can't register global `thumbs.presets` / `thumbs.srcsets`, **you must add these to your site's `site/config/config.php`** — the snippet reads them by name:

```
return [
    'thumbs' => [
        'presets' => [
            // Blurred LQIP placeholders (blur-up effect)
            'swiper-lqip-horiz' => ['width' => 40, 'height' => 23, 'crop' => true, 'quality' => 30, 'blur' => 4, 'format' => 'webp'],
            'swiper-lqip-vert'  => ['width' => 23, 'height' => 40, 'crop' => true, 'quality' => 30, 'blur' => 4, 'format' => 'webp'],
        ],
        'srcsets' => [
            // Landscape (16:9) — used when Orientation = Horizontal
            'swiper-horiz' => [
                '640w'  => ['width' =>  640, 'height' =>  360, 'crop' => true, 'quality' => 80, 'format' => 'webp'],
                '900w'  => ['width' =>  900, 'height' =>  506, 'crop' => true, 'quality' => 82, 'format' => 'webp'],
                '1400w' => ['width' => 1400, 'height' =>  788, 'crop' => true, 'quality' => 85, 'format' => 'webp'],
                '1920w' => ['width' => 1920, 'height' => 1080, 'crop' => true, 'quality' => 85, 'format' => 'webp'],
            ],
            // Portrait (9:16) — used when Orientation = Vertical
            'swiper-vert' => [
                '480w'  => ['width' =>  480, 'height' =>  854, 'crop' => true, 'quality' => 80, 'format' => 'webp'],
                '640w'  => ['width' =>  640, 'height' => 1138, 'crop' => true, 'quality' => 82, 'format' => 'webp'],
                '810w'  => ['width' =>  810, 'height' => 1440, 'crop' => true, 'quality' => 85, 'format' => 'webp'],
                '1080w' => ['width' => 1080, 'height' => 1920, 'crop' => true, 'quality' => 85, 'format' => 'webp'],
            ],
        ],
    ],
];
```

**How it maps to the Panel:**

- The **Orientation** field (Layout tab) selects which srcset the slide uses — `swiper-horiz` (Horizontal) or `swiper-vert` (Vertical), plus the matching `swiper-lqip-*` placeholder.
- The largest entry in the chosen srcset doubles as the `` fallback for browsers that don't support `srcset`.
- The `sizes` attribute is computed per slide from **Slides Visible**(`slidesPerView`) and **Gap Between Slides** (`spaceBetween`), so the browser downloads an image matched to the slot it actually fills — not the whole viewport. A single full-width slide stays `100vw`; 3-per-view becomes `calc((100vw − gaps) / 3)`; `auto` assumes 3 across (a safe floor of at least three images per page width). Define enough srcset steps (the sets above have four) so the browser has candidates at every slot size.
- Slides show the **whole** orientation crop (`object-fit: contain`), so it fills its constrained axis without being re-cropped to the box: **Vertical** (portrait) crops fill the slide **height**, **Horizontal** (landscape) crops fill the **width**. Any leftover space is backed by the blurred LQIP, so letterbox areas read as intentional rather than empty bars.
- All crops are **webp** for smaller payloads (the 1920px landscape crop is typically ~20% the size of the source JPG).

> The descriptor keys (`640w`, `900w`, …) must be valid srcset width descriptors — Kirby uses them verbatim in the generated `srcset` attribute. Keep the names `swiper-horiz`, `swiper-vert`, `swiper-lqip-horiz`, `swiper-lqip-vert` exactly, since the snippet looks them up by name.

Thumbs are generated on demand by Kirby's media manager and cached under `/media`.

---

Manual asset loading
--------------------

[](#manual-asset-loading)

By default the snippet injects Swiper's CDN links at the point the block is rendered in the page body. For performance-sensitive sites you may want to place them in `` instead. Add this to your head snippet:

```