Guide / Controls / Layout

Pages

Swipe between pages

When to use it. A horizontally paged container that reveals one panel at a time. Each panel is a group (its own label, grid, and nested children), so a carousel is a "set of groups" you swipe between. The active page index is the control value, so it syncs and fires actions, and a jump of several pages riffles through the intermediate ones.

Type
carousel
Also titled
Carousel
Default size
3 rows × 2 columns
Symbol
rectangle.stack
Docs
Docs complete
Search for it as
  • swipe
  • slider
  • slideshow
  • gallery
  • pager
  • pages
Pages: Paged (the default) with a starting page
Rendered by the app

Fields

7 fields you can set on a carousel control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
StylecarouselModechoiceone of 3paged

How the pages are laid out as you swipe

Switches between one full page at a time, a tilted row of neighbors, or a stack of cards.

  • paged defaultone full-width page at a time that snaps into place
  • coverflowthe active page centered with smaller tilted neighbors at the sides
  • deckpages stacked like cards; the front card swipes away to show the next
Indicatorindicatorchoiceone of 3dots

The little marks that show which page you are on

Draws a row of dots or bars below the pages with the current one in the accent color, or hides it.

  • dots defaulta row of small round dots
  • barsa row of short flat bars
  • noneno page marks shown
autoAdvanceautoAdvancenumber0–60step 10

Turns the pages by itself on a timer

Moves to the next page every this many seconds (0 to 60); 0 keeps it manual.

Looploopon / offfalse (off)

Lets the pages go round in a circle

On, swiping past the last page returns to the first and the reverse; off, the ends resist with a rubber-band.

panelspanelsobject—

The pages themselves

Supplies the list of pages; each group definition becomes one swipeable page holding its own controls.

containerAnimationcontainerAnimationobject—

How the pages animate when switching

Tunes the page transition: motion profile, duration, bounce and the side or stack shape in coverflow and deck.

defaultValuedefaultValuenumberstep 10

Which page shows first

Opens on this page number when the layout appears, counting from 0 for the first page.

Theme fields

Restyle one control by setting these in its theme object; a layout's theme sets them for every control.

Theme fields
FieldTypeDefaultWhat it does
surfacePrimarytheme.surfacePrimarycolor#FFFFFF0F

The fill behind each page

Colors the card behind every page; a low-opacity white gives a faint glass tint.

accentColortheme.accentColorcolor#667eea

The color of the current page mark

Colors the dot or bar for the page you are on in the indicator.

cornerRadiustheme.cornerRadiusnumber0–30 ptstep 112

How round the page corners are

Rounds each page card's corners by this many points (0 square to 30 very round).

Frosted glasstheme.blurEnabledon / offtrue (on)

How thick the page outline is

Sets the outline width around each page card in points (0 hides it, 5 is heavy).

Card spacingtheme.cardPaddingnumber0–32 ptstep 112

The softer color of supporting writing

Colors the secondary text inside the pages, such as captions and hints.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you swipe to another pagevaluechangenumber

the position of the page you landed on, counting from 0

Example: 1

Receives

Receives
TakesFromTypeWhat it does
valuefollowhub, mqtt, http, store, defaultnumber

the position of the page to show, counting from 0

the carousel pages to it with animation, riffling through any pages in between

Example: 1

Examples

5 examples, each one a control you can paste into a layout.

Paged (the default) with a starting page

Shows the default paged style, the dots indicator and defaultValue: it opens on the second page and snaps one page at a time.

JSON 15 lines
{
  "type": "carousel",
  "id": "pages",
  "position": [0, 0],
  "span": [3, 3],
  "carouselMode": "paged",
  "indicator": "dots",
  "defaultValue": 1,
  "panels": [
    { "type": "group", "id": "p1", "label": "One", "position": [0,0], "grid": { "columns": 1, "rows": 1 },
      "children": [ { "type": "label", "id": "p1-l", "position": [0,0], "text": "First page" } ] },
    { "type": "group", "id": "p2", "label": "Two", "position": [0,0], "grid": { "columns": 1, "rows": 1 },
      "children": [ { "type": "label", "id": "p2-l", "position": [0,0], "text": "Second page" } ] }
  ]
}

Open in CAR-TER

Pages: Paged (the default) with a starting page
Rendered by the app

Coverflow of scenes, synced

Shows coverflow with loop, tuned side tilt, a sync that sets the page from the server and an action that sends the new page index when you swipe.

JSON 19 lines
{
  "type": "carousel",
  "id": "scenes",
  "position": [0, 0],
  "span": [3, 4],
  "carouselMode": "coverflow",
  "indicator": "dots",
  "loop": true,
  "containerAnimation": { "profile": "smooth", "sideScale": 0.78, "sideRotation": 50 },
  "defaultValue": 0,
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "scene" }, "valuePath": "index" }],
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hub", "type": "scene", "payload": { "index": "{{value}}" } } },
  "panels": [
    { "type": "group", "id": "home", "label": "Home", "position": [0,0], "grid": { "columns": 1, "rows": 1 },
      "children": [ { "type": "label", "id": "home-l", "position": [0,0], "text": "Home scene" } ] },
    { "type": "group", "id": "away", "label": "Away", "position": [0,0], "grid": { "columns": 1, "rows": 1 },
      "children": [ { "type": "label", "id": "away-l", "position": [0,0], "text": "Away scene" } ] }
  ]
}

Open in CAR-TER

Pages: Coverflow of scenes, synced
Rendered by the app

Auto-advancing deck

Shows deck with the bars indicator, autoAdvance and loop: the front card swipes away every 4 seconds, forever, over a fanned stack of four cards.

JSON 11 lines
{
  "type": "carousel",
  "id": "promos",
  "position": [0, 0],
  "carouselMode": "deck",
  "indicator": "bars",
  "autoAdvance": 4,
  "loop": true,
  "containerAnimation": { "deckVisibleCount": 4, "deckOffsetStep": 18, "deckRotation": 3 },
  "panels": []
}

Open in CAR-TER

Pages: Auto-advancing deck
Rendered by the app

Bare pages with no indicator

Shows indicator: none with loop off: no page marks, and the ends rubber-band instead of wrapping.

JSON 9 lines
{
  "type": "carousel",
  "id": "quiet",
  "position": [0, 0],
  "indicator": "none",
  "loop": false,
  "containerAnimation": { "profile": "instant", "multiStep": false },
  "panels": []
}

Open in CAR-TER

Pages: Bare pages with no indicator
Rendered by the app

Themed glass pages with square edges

Shows the theme fields: a darker tinted card, a green current-page mark, sharper corners, a thicker border and tighter inner spacing.

JSON 7 lines
{
  "type": "carousel",
  "id": "themed",
  "position": [0, 0],
  "theme": { "accentColor": "#34C759", "surfacePrimary": "#00000040", "cornerRadius": 4, "borderWidth": 2, "borderColor": "#34C75966", "cardPadding": 6, "blurEnabled": false, "foregroundColor": "#FFFFFF", "secondaryColor": "#FFFFFF80" },
  "panels": []
}

Open in CAR-TER

Pages: Themed glass pages with square edges
Rendered by the app

Note on editor fields

Every hinted field here (Style, Indicator, Loop) changes something on screen; panels and containerAnimation are edited in the layout structure and the animation tab rather than by a single control.

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Paged (the default) with a starting page” on your phone.

    carterkit demo carousel --example 'Paged (the default) with a starting page'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Modes

paged (default)

One full-width panel at a time, with a spring snap and rubber-band at the ends (unless loop).

coverflow

The active panel is centered; neighbors are scaled down, pushed to the sides, rotated in 3D, and faded. Tune with containerAnimation.sideScale, sideRotation, sideSpacing, sideOpacity.

deck

Panels stack in front of/behind each other with depth; the front card swipes away to reveal the next. Tune with containerAnimation.deckVisibleCount, deckScaleStep, deckOffsetStep, deckRotation.

Animation Customization

All motion lives in the optional containerAnimation object:

Field Type Default Description
profile string bouncy snappy/smooth/bouncy/gentle/instant
duration number — Override transition seconds
bounce number — Spring bounce 0–1
multiStep bool true Riffle through pages on a multi-page jump
stepInterval number 0.12 Seconds per intermediate step
sideScale number 0.82 (coverflow) neighbor scale
sideRotation number 45 (coverflow) neighbor 3D rotation°
sideSpacing number 0.55 (coverflow) neighbor offset, fraction of width
sideOpacity number 0.6 (coverflow) neighbor opacity
deckVisibleCount number 3 (deck) visible stacked cards
deckScaleStep number 0.06 (deck) scale reduction per layer
deckOffsetStep number 14 (deck) point offset per layer
deckRotation number 0 (deck) fan rotation° per layer

Theming

Panels render as glass cards from the active theme (surfacePrimary, cornerRadius, borderColor, cardPadding). The active indicator uses accentColor. Set hideBackground on a panel for a transparent page, or per-child theme overrides inside a panel.

Generated from ControlDocs/carousel.md. Something unclear or missing? Tell me.