views

Views represent slides, pages, or artboards — named rectangular regions on the infinite canvas.

What Views Represent

A view defines a visible area on the canvas that corresponds to a slide in presentation mode or a page in print/export. Objects can be associated with a view via their vi field, making their coordinates relative to that view’s origin.

StoredView Fields

Field Type Default Description
name string (required) Display name (e.g., "Page 1", "Title Slide")
x number (required) X position on the infinite canvas
y number (required) Y position on the infinite canvas
width number 1920 View width in pixels
height number 1080 View height in pixels
backgroundColor string — Background color (hex)
backgroundGradient StoredBackgroundGradient — Background gradient (takes precedence over backgroundColor)
backgroundImage string — Background image file ID
backgroundFit 'contain' | 'cover' | 'fill' | 'tile' — How background image is sized
showBorder boolean — Whether to show the view border in the editor
transition object — Slide transition for presentation mode
notes string — Speaker notes (plain text)
hidden boolean — If true, visible in editor at 50% opacity but invisible in presentation mode
duration number — Auto-advance duration in seconds (presentation mode)
tpl string — TemplateId reference — view inherits template background when own background fields are absent
View fields use full names

Unlike objects and containers, view fields use human-readable names (backgroundColor, not bc). This is because views are low-volume data (typically dozens, not thousands) — readability was prioritized over wire efficiency.

View Ordering

The vo array holds ViewId strings in presentation order:

// vo: Y.Array<string>
const viewOrder = doc.vo.toArray()  // ["m4Jf_L1pZq8w", "Xk2n_R8vHwYq", ...]

// First view in presentation
const firstViewId = doc.vo.get(0)
const firstView = doc.v.get(firstViewId)

// Reorder: move view from index 2 to index 0
doc.vo.delete(2, 1)
doc.vo.insert(0, [viewId])

Page-Relative Coordinates

When an object’s vi field is set, its xy position is interpreted relative to the view’s origin (x, y), not the global canvas:

Global position = (view.x + object.xy[0], view.y + object.xy[1])

This allows slides to be repositioned on the canvas without affecting the relative positions of their objects.

Background System

View backgrounds resolve in priority order:

  1. backgroundGradient — if present, renders a gradient background
  2. backgroundImage — if present (and no gradient), renders an image
  3. backgroundColor — if present (and no gradient/image), renders a solid color
  4. Template background — if tpl is set and the view’s own background fields are absent, the template’s background is used

StoredBackgroundGradient

Field Type Default Description
gt 'l' | 'r' — Gradient type: 'l'=linear, 'r'=radial
ga number — Angle in degrees (linear gradients only)
gx number — Center X position 0–1 (radial gradients only)
gy number — Center Y position 0–1 (radial gradients only)
gs [string, number][] — Color stops: [color, position] pairs where position is 0–1

Transitions

The transition object defines how a slide enters during presentation mode:

Field Type Default Description
type 'none' | 'fade' | 'slide' | 'zoom' | 'push' 'none' Transition effect
duration number — Duration in milliseconds
direction 'left' | 'right' | 'up' | 'down' — Direction (for slide and push types)

Default Dimensions

New documents use 1920×1080 (Full HD landscape) as the default view size. This can be changed via the defaultViewWidth and defaultViewHeight metadata fields.

Hidden Views

When a view has hidden: true:

  • In the editor: The view is displayed at 50% opacity to distinguish it from active views
  • In presentation mode: The view is skipped entirely
  • In view order: The view remains in the vo array at its current position