Scroll States in Builder 2.0

1. Purpose & Scope

This article documents the Scroll States MVP, the flagship feature of the Tiled v58.0.0 March 2026 release. Scroll States enable content creators to define named positional states within a scrolling microapp page or scroll container, creating structured, navigable experiences where content reveals, animations, and transitions are tied to specific scroll positions.

Scope: All Tiled users with Builder 2.0 access (Editor role and above). This feature is exclusive to Builder 2.0. Builder 1.0 scroll states are supported via the assisted migration flow documented in KB-v58-02.

2. Control Objective

The control objective is to provide content creators with a complete, production-ready system for defining and managing scroll states within Builder 2.0 microapps — from creation through to import/export and migration — such that scroll-state-based experiences are consistent, reliable, and portable across the Tiled platform.

3. Feature Components

The Scroll States MVP shipped across seven tickets, each delivering a distinct component of the system:

Scroll States Panel UI (TD-6421)	A dedicated Scroll States panel in the Builder 2.0 sidebar. Lists all defined scroll states for the current page, shows the name and scroll offset of each state, and provides controls to create, rename, reorder, and delete states.
State Synchronization (TD-6422)	Scroll state definitions are synchronized in real time between the panel UI and the canvas. Changes to a state's offset (by scrolling the canvas) update the panel immediately, and vice versa.
Import/Export Support (TD-6424)	Scroll state definitions are included in microapp import/export packages. Exporting a microapp with scroll states produces a complete package that, when imported, restores all state names, offsets, and associated configurations.
State Selection (TD-6441)	Clicking a scroll state in the Scroll States panel scrolls the canvas to that state's position, making it the active editing context. The selected state is highlighted in the panel.
Drag & Drop Reordering (TD-6442)	Scroll states in the panel can be reordered by dragging. Reordering does not change the scroll offsets of individual states — it only changes the display order in the panel.
Hotkeys (TD-6439)	Keyboard shortcuts for scroll state navigation: cycle forward and backward through scroll states without using the panel. Supports rapid review of state-by-state content during editing.
Properties Panel Support (TD-6440)	When a scroll state is active (selected in the panel), the Properties panel updates to show properties scoped to that state — including background, visibility overrides, and other state-specific configurations.

4. Creating and Managing Scroll States

4.1 Creating a Scroll State

1. Open a microapp in Builder 2.0.

2. Navigate to the Scroll States panel in the left or right sidebar.

3. Scroll the canvas to the position where you want to define a state.

4. Click Add State (or the + button) in the Scroll States panel.

5. The new state is created at the current canvas scroll position with a default name (e.g., State 1).

6. Double-click the state name in the panel to rename it.

4.2 Editing a Scroll State

7. Click the target scroll state in the Scroll States panel to select it and scroll the canvas to its position.

8. Scroll the canvas to the new desired position for the state.

9. The state's offset updates automatically as you scroll while it is selected.

10. Use the Properties panel to configure state-specific settings: background, tile visibility overrides, and other per-state properties.

4.3 Using Hotkeys

Next State	Cycle forward to the next scroll state in the panel order.
Previous State	Cycle backward to the previous scroll state.
Jump to State	Select a specific state number using the assigned hotkey sequence (see Builder 2.0 keyboard shortcut reference).

4.4 Import/Export with Scroll States

11. Export any microapp containing scroll states using the standard Export action from the Library.

12. The exported package file includes all scroll state definitions, offsets, names, and per-state property configurations.

13. Importing the package into any Tiled Library restores the microapp with all scroll states intact.

14. Verify imported scroll states by opening the Scroll States panel and confirming all states are listed at their correct offsets.

5. Scroll State Properties Reference

Name	User-defined label for the state. Displayed in the panel and referenced in click events that target this state.
Scroll Offset	The vertical (or horizontal) pixel position of the canvas when this state is active. Set by scrolling the canvas while the state is selected.
Background	Optional per-state background override. Set a different background image or color for this state without affecting other states on the same page.
Visibility Overrides	Per-state tile visibility can be set — tiles can be shown or hidden differently for each scroll state, enabling content reveal animations tied to scroll position.
Click Event Target	Scroll states are addressable by click events. A tile's click event can navigate to any named scroll state on the current or another page.

6. QA Validation Summary

QA Scope: Scroll States received end-to-end QA coverage in the v58.0.0 release cycle: state creation, switching, nested states, import/export, and migration paths were all validated in preprod before the March 4, 2026 production release.

State creation & naming	Verified: states created at correct offsets, names persisted.
State switching (panel + hotkeys)	Verified: panel click and hotkey navigation move canvas to correct position.
Nested states	Verified: scroll states within nested scroll containers resolve independently.
Import/export roundtrip	Verified: exported package restores all states with correct names and offsets on import.
Properties panel per-state	Verified: background and visibility overrides apply to the correct state only.

7. Related Controls

• KB-v58-02 — 1.0 → 2.0 Scroll State Migration (assisted migration for existing microapps with scrolls)

• KB-v58-05 — Bug Fix Bulletin (TD-6521–6526: Scroll States bug fixes shipped alongside the MVP)

8. Change History

v1.0 — March 4, 2026

Initial article. Scroll States MVP shipped in Tiled v58.0.0.

Scroll States in Builder 2.0

Full Scroll States MVP — panel UI, state synchronization, drag & drop, hotkeys, import/export, and properties panel

4.1 Creating a Scroll State