PHPackages                             ianhobbs/kirby-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. ianhobbs/kirby-swiper-block

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

ianhobbs/kirby-swiper-block
===========================

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

v1.1.0(2d ago)10MITPHPPHP >=8.3CI passing

Since Jun 5Pushed 2d agoCompare

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

READMEChangelogDependencies (1)Versions (6)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+

NOTE :: this is still being develped. --pre -beta !!
----------------------------------------------------

[](#note--this-is-still-being-develped---pre--beta-)

### don't use this while this notice is active

[](#dont-use-this-while-this-notice-is-active)

---

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 buttonOverlay OpacityDark overlay on the image (0–90%)Content 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 DirectionHorizontalHorizontal or VerticalSlides 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
-------------

[](#image-presets)

The plugin registers five thumb presets for responsive image serving:

PresetSizeViewport`swiper-xl`1920 × 810≥ 1400 px`swiper-lg`1400 × 590≥ 900 px`swiper-md`900 × 506≥ 640 px`swiper-sm`640 × 480Mobile fallback`swiper-lqip`40 × 17Blurred placeholder (blur-up effect)Thumbs are pre-generated on image upload so the first page load never stalls on thumb generation.

---

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:

```