Skip to main content

Keen Slider

Released in version 1.23.0

The Keen Slider block is a flexible Gutenberg slider container powered by Keen Slider.

It is designed to support multiple content workflows:

  • manual slides using standard blocks
  • image-only slides
  • gallery-style slides
  • post-query slides (via Query Loop blocks)
  • media-folder slides sourced from Happy Files

Each direct child block inside the slider becomes one slide.

What this block creates​

When rendered, the block outputs:

  • a slider wrapper (.wp-block-yoko-core-keen-slider)
  • a Keen track container (.keen-slider.yoko-keen-slider__track)
  • one slide wrapper per direct inner block (.keen-slider__slide.yoko-keen-slider__slide)

If a slide is a direct core/image block, it receives an image-slide modifier class so image alignment/containment rules apply consistently.

Authoring model​

The block is an InnerBlocks container.

  • Add one top-level child block per slide.
  • Use core/group when a single slide needs multiple nested blocks.
  • Query Loop can be used as a slide source by placing it as a direct child.
  • Happy Files can be used as a dynamic image source when you want slides to follow a media folder instead of manual child blocks.

Because each direct child is a slide, avoid nesting all slide content under one single top-level block unless that is your intended structure.

Source modes​

The block supports two main source patterns:

  • Manual / block-driven slides using direct child blocks
  • Happy Files media folder source using images pulled from a selected media folder

When Happy Files source is enabled, the block renders slides from the selected folder and manual child slides are disabled until that source is turned off again.

Block settings​

All settings are available in the block inspector.

Slider Settings​

Loop​

  • Enables looping behavior.
  • Default: true

Drag​

  • Enables drag/swipe interaction.
  • Default: true

Vertical​

  • Switches to vertical track behavior.
  • Default: false

Rubberband​

  • Enables edge elasticity where supported.
  • Default: true

Mode​

Available values:

  • snap
  • free
  • free-snap

Default: free-snap

Origin​

Available values:

  • auto
  • center
  • start

Default: auto

Animation Duration​

  • Transition timing used by slider motion.
  • Default: 500
  • Range: 100 to 2000

Slide Max Height​

  • Optional CSS size applied to all slides.
  • Example values: 520px, 40rem, 70vh
  • When set, slide wrappers inherit that height cap and internal images are constrained to remain inside it.

Responsive Slides​

Per-view settings​

  • Desktop per view (default 1)
  • Tablet per view (default 1)
  • Mobile per view (default 1)

Spacing settings​

  • Desktop spacing (default 24)
  • Tablet spacing (default 16)
  • Mobile spacing (default 12)

Continuous Scroll​

Enable continuous scroll​

  • Turns on automated ongoing motion.
  • Default: false

Scroll duration​

  • Controls speed of each movement step.
  • Lower values feel faster.
  • Default: 12000

Scroll direction​

  • Available values: forward, backward
  • Default: forward

Pause on interaction​

  • Pauses motion during drag/interaction.
  • Default: true

Pause on hover​

  • Pauses while pointer is over slider.
  • Default: true

Pause on focus​

  • Pauses when focus enters slider.
  • Default: true

Happy Files Source​

This source mode is available when the Happy Files plugin is active and at least one media folder exists.

Use Happy Files media folder as source​

  • Switches the block from manual child slides to a server-rendered image source.
  • The editor preview uses the same rendered markup as frontend output.

Happy Files folder​

  • Selects the media folder used as the slide source.
  • Images are rendered in the folder order returned by WordPress unless randomization is enabled.

Randomize images​

  • Shuffles the folder images before rendering.
  • Randomized selections are cached for a short period so frontend output stays stable between requests.

Limit # of images​

  • Caps how many images are rendered from the selected folder.
  • Useful when a folder is shared by many assets but the slider should stay intentionally small.

When Happy Files source is enabled:

  • child slides are disabled
  • the block renders image slides only
  • empty folders render no slides until images are added

Show navigation arrows​

  • Enables previous/next arrow buttons for the slider.
  • Default: false

Arrow location​

  • Available values: sides, below, above
  • Default: sides

Arrow alignment​

  • Available values: start, end
  • Default: end
  • Applies when location is above or below.

Arrow icon​

  • Lets you choose from built-in Dashicon arrow styles via the WordPress icon library picker.
  • Invalid values are normalized to a safe default (arrow-right-alt2).

Arrow colors​

  • Arrow background color and Arrow icon color are optional.
  • When unset, theme-safe defaults are used.

Arrow border radius​

  • Controls button corner roundness.
  • Default: 999
  • Range: 0 to 999

Arrow edge offset​

  • Controls side arrow horizontal offset when location is sides.
  • Positive values move arrows outward from slider edges; negative values move them inward.
  • Default: 0

Styling support​

The block supports native Gutenberg style controls including:

  • background color
  • spacing (margin/padding)
  • alignment (wide, full)

Background color behavior​

When a background color is selected in Gutenberg Styles, that color is applied in both:

  • frontend rendering
  • Gutenberg editor preview

Load behavior and visual stability​

To prevent layout flash before initialization:

  • block starts in a pending state (yoko-keen-slider--pending)
  • slider content fades in after Keen is ready (is-keen-ready)

This reduces layout jump while preserving editor and frontend consistency.

Image slide behavior​

Image slides are centered and constrained:

  • direct image slides are vertically and horizontally centered
  • images inherit slide height constraints when Slide Max Height is set
  • overflow is hidden to prevent bleed outside slide bounds
  • object-fit: contain is used to keep full image visible inside the height cap

Troubleshooting​

Continuous scroll reverses unexpectedly​

Use Scroll direction in Continuous Scroll settings.

The runtime uses direction-aware monotonic index stepping to avoid seam-based route reversal.

My slide content is not split into separate slides​

Each direct child block is one slide. Move each intended slide to the top level under the Keen Slider block.

Slide max height is set but content still feels tall​

Ensure the value includes a valid CSS unit (for example px, rem, vh, %).

Query Loop content appears as a single slide​

That is expected if the Query Loop itself is the top-level child. To make each queried item its own slide, structure content so each item is a direct slide-level child or use grouped slide composition.

Happy Files source options do not appear​

Confirm that the Happy Files plugin is active and that at least one media folder exists.

Happy Files source is enabled but nothing renders​

Check that the selected folder contains media attachments and that any image limit is greater than zero.

Arrow controls require at least one renderable slide in the track. Confirm the slider has content (manual inner blocks or Happy Files images), then verify drag/loop settings and refresh the page.

That is expected on non-looping sliders when the track is at the first or last slide. Enable Loop if you want arrows to stay active at the ends.

Technical notes (for developers)​

  • Block name: yoko-core/keen-slider
  • Dynamic render: src/keen-slider/render.php
  • Frontend runtime: src/keen-slider/view.js
  • Editor UI: src/keen-slider/edit.js
  • Shared styles: src/keen-slider/style.scss
  • Editor styles: src/keen-slider/editor.scss

The Docusaurus sidebar is autogenerated, so adding this file under docs/blocks/ makes it appear in the Blocks section automatically.