Carousel

A tile-based horizontal scroll carousel with CSS scroll-snap, prev/next navigation buttons, and optional dot indicators. Each click of Next/Prev snaps to the adjacent tile. Supports server-rendered tiles (PHP array) or client-side loading from a remote JSON endpoint.

Dot placement defaults to 'below'. Use ->dots('above') or ->dots('none') to change or remove them.

Default — dots below

Server-rendered tiles, dot indicators positioned below the carousel.

Ocean SunsetPhotography

City LightsUrban

Forest PathNature

Desert DunesLandscape

Mountain PeakAdventure

River BendScenic

Coral ReefUnderwater

Aurora BorealisNight Sky

$tiles = [
    ['title' => 'Ocean Sunset',  'href' => '/photos/1', 'imageUrl' => '/assets/ocean.jpg',  'caption' => 'Photography'],
    ['title' => 'City Lights',   'href' => '/photos/2', 'imageUrl' => '/assets/city.jpg',   'caption' => 'Urban'],
    ['title' => 'Forest Path',   'href' => '/photos/3', 'imageUrl' => '/assets/forest.jpg', 'caption' => 'Nature'],
    // ...
];
echo $m->carousel('myCarousel')
    ->tiles($tiles)
    ->dots('below');   // default

Dots above

Navigate with dots placed above the carousel. Use a wider tile width.

Component DesignDesign

Code ArchitectureEngineering

UI PatternsUX

TypographyVisual

Colour TheoryDesign

echo $m->carousel('topDotsCarousel')
    ->tiles($tiles)
    ->tileWidth('200px')
    ->dots('above');

No dots

Carousel with only prev/next buttons — no dot indicators.

echo $m->carousel('noDots')
    ->tiles($tiles)
    ->dots('none');

Single tile — buttons / dots hidden

When only one tile exists, navigation buttons and dots are automatically hidden.

Only ItemStandalone

echo $m->carousel('oneTile')
    ->tile('Only Item', '/link', '/assets/img.jpg', 'Subtitle')
    ->dots('below');

Tiles without images

When no imageUrl is provided, a placeholder icon is shown.

echo $m->carousel('noImages')
    ->tiles([
        ['title' => 'Item Alpha', 'href' => '/item/1', 'caption' => 'Category A'],
        ['title' => 'Item Beta',  'href' => '/item/2', 'caption' => 'Category B'],
    ])
    ->tileWidth('140px')
    ->dots('below');

Remote datasource (client-side)

Pass ->remoteUrl() instead of ->tiles() to load tiles client-side on page load. The endpoint should return { "tiles": [ {title, href, imageUrl, caption}, … ] }. A perPage query param is appended when set via ->perPage().

Tiles load automatically from /demo/carouselData on page load.

echo $m->carousel('ajaxCarousel')
    ->remoteUrl('/api/carousel-tiles')
    ->perPage(8)
    ->dots('below');

// Endpoint response format:
// GET /api/carousel-tiles?perPage=8
// {
//   "tiles": [
//     { "title": "...", "href": "...", "imageUrl": "...", "caption": "..." },
//     ...
//   ]
// }

// JS API (after DOMContentLoaded):
document.addEventListener('DOMContentLoaded', function () {
    var c = m.carousel('ajaxCarousel');

    // Navigate programmatically
    c.next();
    c.prev();
    c.goTo(3);

    // Inspect state
    console.log(c.current()); // current tile index (0-based)
    console.log(c.count());   // total tiles

    // Reload from a different URL
    c.reload('/api/other-tiles', 10);
});

// Listen for change events
document.getElementById('ajaxCarousel')
    .addEventListener('m:carousel:change', function (e) {
        console.log('Active tile:', e.detail.index);
    });

// Listen for remote load completion
document.getElementById('ajaxCarousel')
    .addEventListener('m:carousel:loaded', function (e) {
        console.log('Loaded tiles:', e.detail.count);
    });

Tiles with chips

Pass an optional chip (and optional chipVariant) per tile to show a coloured chip label overlaid in the top-right corner of the tile image. Variants: primary, success, warning, danger, purple, secondary (default), info.

Ocean SunsetPhotography

Featured

Draft

Published

Sold Out

New

// Via ->tiles() array — include chip and optional chipVariant:
$tiles = [
    ['title' => 'Featured', 'href' => '/1', 'imageUrl' => '/img.jpg', 'chip' => 'Featured', 'chipVariant' => 'primary'],
    ['title' => 'Draft',    'href' => '/2', 'imageUrl' => '/img2.jpg', 'chip' => 'Draft',   'chipVariant' => 'warning'],
    ['title' => 'Normal',   'href' => '/3', 'imageUrl' => '/img3.jpg'],   // no chip
];
echo $m->carousel('chipDemo')->tiles($tiles)->dots('below');

// Or via ->tile() directly (chip is 5th param, chipVariant is 6th):
echo $m->carousel('chipDemo')
    ->tile('Featured Item', '/link', '/img.jpg', 'Category', 'Featured', 'primary')
    ->tile('Draft Item',    '/link', '/img2.jpg', null, 'Draft', 'warning')
    ->tile('Normal Tile',   '/link', '/img3.jpg');

// chipVariant: primary | success | warning | danger | purple | secondary (default) | info

JS API

Control the carousel programmatically using m.carousel(id).

Current tile: —

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->carousel($id)`	`string`	Create a Carousel component.
`->tile($title, $href, $imageUrl, $caption, $chip, $chipVariant)`	`string, string, ?string, ?string, ?string, string`	Add a single tile. `imageUrl`, `caption`, and `chip` are optional. `chipVariant` defaults to `'secondary'`.
`->tiles($tiles)`	`array`	Add multiple tiles at once. Each element: `{title, href, imageUrl?, caption?, chip?, chipVariant?}`.
`->remoteUrl($url)`	`string`	Client-side remote datasource URL. Response: `{"tiles":[…]}`. Each tile object may include `chip` and `chipVariant`.
`->perPage($n)`	`int`	Tiles per remote fetch (appended as `?perPage=N`). Default: `0` (load all).
`->dots($placement)`	`string`	Dot indicator placement. `'below'` (default), `'above'`, or `'none'`.
`->tileWidth($css)`	`string`	CSS width of each tile. Default: `'160px'`. Accepts any CSS length.
`->tileGap($px)`	`int`	Gap between tiles in pixels. Default: `12`.

JS JS Methods

Method / Property	Parameters	Description
`m.carousel(id)`	`string\|Element`	Get the Carousel API for the given element ID or DOM element.
`c.goTo(idx)`	`number`	Navigate to tile at zero-based `idx`.
`c.next()`		Navigate to the next tile.
`c.prev()`		Navigate to the previous tile.
`c.current()`		Returns the current tile index (0-based).
`c.count()`		Returns the total number of tiles.
`c.reload(url?, perPage?)`		Reload tiles from a remote URL. Defaults to configured `remoteUrl`/`perPage`.

EVENT Events

Event Name	Detail	Description
`m:carousel:change`	`{ index: number }`	Fired on the carousel element when the active tile changes.
`m:carousel:loaded`	`{ count: number }`	Fired on the carousel element after remote tiles have loaded.