API Reference

Constructor Options

Required and optional parameters passed to new Zumly({...}).

Transitions

Configure how zoom animations look and feel. All nested under transitions: {...}.

Navigation Options

Control lateral, depth, and input navigation behavior.

lateralNav

depthNav

new Zumly({ ..., depthNav: { style: 'rings' } })

/* Mark a level that needs attention */
.z-depth-ring[data-view="security"] { stroke: tomato; opacity: 1; }
.z-depth-band[data-view="security"] .z-depth-band-mark { background: tomato; }

inputs

gestures

new Zumly({ ..., gestures: { follow: true, threshold: 0.4 }, inputs: { pinch: true } })

labels

labels: {
  back: 'Volver a {title}',
  goTo: view => `Ir a ${view.title}`,
  prev: false,
  next: false
}

Methods

Navigation promises settle after transitions finish. Await each call to navigate sequentially; calls made during an active load or animation are ignored.

// Programmatic navigation
const app = new Zumly({ mount: '#canvas', initialView: 'home', views });
await app.init();

await app.zoomTo('detail');         // zoom in
await app.zoomTo('deep');           // zoom deeper
await app.back();                   // zoom out

await app.goTo('page2', { mode: 'lateral' });  // slide to sibling
await app.back();                   // back to previous sibling

await app.zoomOut(2);               // two levels up, one transition
await app.zoomOut({ to: 'home' });  // up to an ancestor by name

console.log(app.zoomLevel());           // 2
console.log(app.getCurrentViewName());  // 'detail'

Lifecycle Events

Hook into the zoom lifecycle with .on() and .off().

app.on('viewMounted',  ({ viewName, node }) => { /* ... */ });
app.on('beforeZoomIn', ({ viewName }) => { /* ... */ });
app.on('afterZoomIn',  ({ viewName, zoomLevel }) => { /* ... */ });
app.on('beforeZoomOut', ({ zoomLevel }) => { /* ... */ });
app.on('afterZoomOut',  ({ zoomLevel }) => { /* ... */ });
app.on('beforeLateral', ({ viewName, from, isBack }) => { /* ... */ });
app.on('afterLateral',  ({ viewName, from, isBack }) => { /* ... */ });
app.on('zoomOutProgress', ({ phase, progress }) => {
  backButton.style.setProperty('--progress', progress);  // follow the gesture
});
app.on('destroy',       () => { /* ... */ });

View Sources

Views can be defined in many ways. The resolver detects the type automatically.

Function and object views receive a context: target (a fresh div; if the function returns nothing, target is the view: give it your classes and render only the content), props (the trigger's data attributes), trigger, context (componentContext), onCleanup(fn) (runs when the view is discarded) and onActivate(fn) (runs each time the view becomes current again without being rendered anew, for example after zooming back out to it). A template with several root elements is wrapped in one .z-view.

A view can carry a human-readable name for the navigation UI: title in an object view (or a function view's title property), or data-title on the view's root element, which wins. Without one, the view name is used. The back button, the sibling dots, getViewStack() and the view's aria-label show it.

// HTML string
const myView = '<div class="z-view">Hello</div>';

// Function returning markup (called fresh each time)
function myView({ props }) {
  return `<div class="z-view">${props.id}</div>`;
}

// Function filling ctx.target, repainting when the user comes back
function room({ target, onActivate }) {
  target.className = 'z-view room';
  const paint = () => { target.innerHTML = `<h1>${state.temperature}°</h1>`; };
  paint();
  onActivate(paint);
}

// Async function
async function myView() {
  const html = await fetch('/partial.html').then(r => r.text());
  return html;
}

// Object with render() and optional mounted()
const myView = {
  render(ctx) { return '<div class="z-view">...</div>'; },
  mounted(node) { console.log('inserted', node.offsetWidth); }
};

// URL (fetched and cached for 5 minutes)
const myView = '/views/detail.html';

// Human-readable title for the navigation UI
const security = { title: 'Security', render: () => '<div class="z-view">...</div>' };
const log = '<div class="z-view" data-title="Audit log">...</div>';

Per-Trigger Attributes

Override global settings on individual trigger elements using data attributes.

<div class="zoom-me"
     data-to="detail"
     data-with-duration="2s"
     data-with-ease="cubic-bezier(.4,0,.2,1)"
     data-with-effects="blur(5px)|blur(10px)"
     data-deferred
     data-id="42"
     data-category="settings">
  Zoom in
</div>

// In the target view function:
function detail({ props }) {
  console.log(props.id);       // "42"
  console.log(props.category); // "settings"
}

Required Classes