SPA & View Transitions (lila-client.js)

Lila v2.0 brings an authentic Single Page Application (SPA) experience to server-rendered Python without requiring Node.js, Webpack, or complicated hydration setups. Powered by View Transitions API, intelligent hover prefetching, and reactive Tailwind CSS UI components.

How it Works

Page templates rendered with render() are wrapped in lila/base.jinja automatically (see Templates). The runtime automatically intercepts internal links, loads destination HTML in the background, smoothly cross-fades content inside <div id="lila-outlet" data-lila-outlet>, and executes scripts:

<!-- Only the outlet content transitions smoothly -->
<div id="lila-outlet" data-lila-outlet class="flex-1 flex flex-col">
  {% block content %}{% endblock %}
</div>

<!-- Persistent elements keep state (audio players, sidebar menus, chats) -->
<aside data-persist="true" id="main-sidebar">
  ...
</aside>

<script src="{{ public('js/lila-client.js') }}"></script>

Navigation lifecycle

• lila:before-swap — fired before the page content is replaced (page-scoped sockets/timers clean up here).
• The <title>, meta tags, canonical, <html lang> and every [data-lila-head] tag (styles/scripts/JSON-LD from render()) are synchronized. Identical tags are kept, so libraries are not downloaded twice.
• Persisted elements (data-persist="true", e.g. a sidebar) keep their DOM, but their links take the class/aria-current rendered for the new page, so the active item follows navigation.
• Scripts run in document order: an external <script src> finishes loading before the next inline script runs.
• lila:page-load / lila:navigate / lila:load — fired after the swap (use Lila.onPageLoad(fn)).
• Page scripts run on every visit: use var/function for globals and call init code directly (DOMContentLoaded only fires on the first full load).
• Hover prefetch is de-duplicated and never stores redirected responses (e.g. an expired session redirecting to /login). Same-page #hash links scroll natively.

lila-client.js is loaded in the <head> of the default layout, so inline page scripts can call lila(), Http(), lilaSSE() or lilaWS() on the first load too. Live updates without WebSockets: Server-Sent Events (data-sse).

HTML attributes reference

Everything below works without writing JavaScript, survives SPA navigations and is re-applied to content inserted with data-target or partials. Escape closes drawers and dropdowns.

Drawers in any direction

<button data-drawer="#mobile-menu" aria-expanded="false">☰</button>

<aside id="mobile-menu" data-drawer-panel data-orientation="left" data-size="18rem"
       class="bg-white dark:bg-slate-900 p-6">
  <button data-drawer-close aria-label="Close">&times;</button>
  <nav><a href="/">Home</a><a href="/docs">Docs</a></nav>   <!-- links close it -->
</aside>

<!-- bottom sheet -->
<button data-drawer="#filters">Filters</button>
<section id="filters" data-drawer-panel data-orientation="bottom" class="bg-white p-6 rounded-t-2xl">...</section>

JS: Lila.drawer('#mobile-menu', 'open') or lila('drawer', { id: 'mobile-menu', action: 'close', orientation: 'top' }). Events: lila:drawer-open, lila:drawer-close. Focus moves into the drawer and back to the trigger.

Everyday helpers

<!-- dropdown -->
<div class="relative">
  <button data-dropdown="#user-menu">Account ▾</button>
  <ul id="user-menu" hidden class="absolute right-0 mt-2 card p-2">
    <li><a href="/profile">Profile</a></li>
    <li><a href="/logout" data-no-router>Log out</a></li>
  </ul>
</div>

<!-- live search over a list + "no results" -->
<input type="search" data-filter="#products" placeholder="Search...">
<ul id="products"><li>Coffee</li><li>Tea</li></ul>
<p data-filter-empty="#products" hidden>No results</p>

<!-- filters that navigate (SPA) as you type/change -->
<form action="/products" method="get" data-navigate data-autosubmit="300">
  <input type="search" name="q"><select name="sort"><option>new</option><option>price</option></select>
</form>

<!-- password + counter + copy -->
<input id="pwd" type="password" name="password">
<button type="button" data-password-toggle="#pwd" data-show-text="Show" data-hide-text="Hide">Show</button>
<textarea name="bio" maxlength="160" data-char-count="#bio-count"></textarea><small id="bio-count"></small>
<button data-copy="#api-key" data-copy-message="Copied!">Copy key</button>

<!-- dismissible alert, class toggle, smooth scroll, local dates -->
<div class="alert" data-removable>Saved! <button data-remove aria-label="Close">&times;</button></div>
<button data-toggle-class="hidden" data-toggle-target="#advanced">Advanced</button>
<button data-scroll>↑ Top</button>
<time data-local-time datetime="{{ order.created_at }}" data-format="relative"></time>

Forms & actions without JavaScript

Add data-lila-form to a form (or any of data-snackbar, data-toast, data-target, data-redirect) and lila-client.js sends it with Http():

1. Native HTML5 validation runs first (required, type, min/max, minlength, pattern...) plus data-match="other_field" for confirmations.
2. Method from method (or data-method for PUT/PATCH/DELETE), URL from action. Fields are sent as JSON (Object.fromEntries(new FormData(form)), repeated names become arrays); forms with files are sent as multipart/form-data. The CSRF token is attached automatically.
3. Every submit button is disabled while the request runs; the clicked one shows a spinner (and data-loading-text). Buttons are re-enabled when the answer arrives, on network errors and after data-timeout ms (default 20000, the request is aborted).
4. The answer is normalized: success/ok false or an HTTP error = error; message from message, msg, detail or error. 422 errors ([{"field": "message"}]) are shown under each field (or in [data-error-for="field"]).
5. Feedback: data-snackbar, data-toast="Success title" (+ data-toast-error) and/or a [data-message] element inside the form that is shown with success/error styles.
6. On success: data-redirect="/path" (or a redirect field in the JSON, SPA navigation unless data-no-router; data-redirect-delay ms), data-reset (whole form) or data-reset="password,password_2", data-reload, data-target="#sel" + data-swap="inner|outer|append|prepend|text" with an HTML answer or {"html": "..."}, data-refresh="#datatable-id" (re-fetches a datatable(url=...)).
7. data-callback="fnName" calls window.fnName(data, element, result) on success and error. Events lila:request, lila:success and lila:error bubble from the element.

<form action="/register" method="post" data-lila-form
      data-toast="Account created" data-toast-error="Error" data-redirect="/dashboard">
  <input name="name" required minlength="2">
  <input name="email" type="email" required>
  <input name="password" type="password" required minlength="8">
  <input name="password_2" type="password" required
         data-match="password" data-match-message="Passwords do not match">
  <label><input type="checkbox" name="terms" value="1" data-unchecked="0"> Accept</label>

  <div data-message hidden></div>               <!-- optional inline message -->
  <button type="submit" data-loading-text="Creating...">Create account</button>
</form>

Buttons and links use the same pipeline with data-action (links with data-action are never handled by the SPA router). data-confirm asks first; data-body is JSON; data-include="#form-or-container" merges its fields.

<button data-action="/api/items/3" data-method="DELETE" data-confirm="Delete item #3?"
        data-snackbar data-refresh="#items-table">Delete</button>

<a href="#" data-action="/api/stats" data-method="GET" data-target="#stats">Refresh stats</a>
<div id="stats"></div>

<button data-action="/api/publish" data-body='{"id": 7}' data-callback="afterPublish">Publish</button>
<script>
  function afterPublish(data, button, result) { if (result.ok) button.remove(); }
</script>

<!-- Show / hide an element (hidden attribute or .hidden class) -->
<button data-toggle-hidden="#danger-zone" aria-expanded="false">Delete account</button>
<div id="danger-zone" hidden>...</div>

From JavaScript: Lila.submit(form), Lila.action(button), Lila.refresh("#table"). Add data-native to a form to keep the browser's normal submit. The auth scaffold (lila auth) uses only these attributes, without page scripts.

UI Components Reference

All components are styled natively with Tailwind CSS, with full dark-mode support:

lila('toast', {
  title: 'Profile Updated',
  description: 'Your changes have been saved successfully.',
  type: 'success', // 'info' | 'success' | 'warning' | 'error'
  position: 'bottom-right',
  duration: 4000
});

lila('snackbar', {
  message: 'Item removed from database',
  type: 'info',
  duration: 3000
});

new ResponsiveDataTable('containerId', {
  data: users,
  columns: [
    { title: 'ID', key: 'id' },
    { title: 'Name', key: 'name' },
    { title: 'Email', key: 'email' }
  ],
  rowsPerPage: 10,
  search: true,
  pagination: true,
  edit: (e, item) => openEditModal(item),
  delete: (e, item) => deleteRecord(item)
});

<div data-carousel
     data-carousel-autoplay="4000"     <!-- ms, 0 = off (default) -->
     data-carousel-loop="true"         <!-- wrap around (default true) -->
     data-carousel-arrows="true"       <!-- prev/next buttons (default true) -->
     data-carousel-indicators="true"   <!-- dots (default true) -->
     data-carousel-pause="true"        <!-- pause on hover (default true) -->
     class="h-72 rounded-2xl">
  <div data-carousel-slide><img src="/img/1.webp" alt="" class="w-full h-full object-cover"></div>
  <div data-carousel-slide><img src="/img/2.webp" alt="" class="w-full h-full object-cover"></div>
  <!-- several per view: give the slide a basis class -->
  <div data-carousel-slide class="basis-full md:basis-1/3 p-2"><div class="card h-full">Card</div></div>
</div>

{{ carousel([{"image": "img/1.webp", "title": "Fast", "text": "...", "href": "/docs"}], autoplay=5000) }}

// Markup added dynamically (or classes .carousel/.carousel-track/.carousel-item):
var sliders = lila('carousel', { selector: '.my-carousel', autoplay: 4000, loop: false }); // array
var slider = lila('carousel', { el: document.getElementById('hero') });                   // one

slider.next(); slider.prev(); slider.go(2); slider.stop(); slider.start();
slider.index;  slider.length;
document.getElementById('hero').addEventListener('lila:carousel-change', (e) => console.log(e.detail.index));

// Press Ctrl+K anywhere or trigger manually:
lila('command', { action: 'toggle' });

// Automatically extracts and attaches CSRF tokens and invalidates prefetch cache
const res = await Http('/api/users', 'POST', { name: 'Alex', email: 'alex@example.com' });
if (res.success) {
  lila('toast', { title: 'Success', description: 'User created', type: 'success' });
}