Islands

Pages ship no JavaScript by default. A tag exported from a file in src/islands/ is an island: it's server-rendered like everything else, then comes alive in the browser.

# src/islands/counter.imba
export tag Counter
	count = 0

	<self>
		<button @click=(count++)> "Clicked {count} times"

# any page
import {Counter} from '../islands/counter'

<Counter count=5>

How it works

1. On the server, the island renders like any tag, so its HTML is in the page from the start. Its fields (count above) are saved into the HTML as JSON.
2. In the browser, the page loads the island's script, which restores the fields and lets Imba take over the element. Clicks work, and <Counter count=5> starts at 5, not 0.

Only pages that render an island load its script, and all islands share one copy of Imba's runtime (about 13 KB gzipped).

Things that must run in the browser

Some things can't be known when the site is built: the current time, the visitor's screen, what they've typed. A shop's "Open now" badge is a good example: it renders a neutral placeholder on the server, then works out the real status in mount, which only runs in the browser:

export tag OpenNow
	hours = []
	status = null

	def mount
		status = check!
		render!

	<self>
		if status
			status.text
		else
			"See opening hours"

Rules for fields

• Fields are saved as JSON, so keep them plain data: strings, numbers, booleans, arrays, objects. Functions and elements are skipped with a warning.
• To save only some fields: static island = ['count'].
• Content passed into an island's <slot> isn't carried over to the browser.

Do you need one?

Often not. A FAQ can be <details>/<summary>, with no JavaScript at all. A mobile menu, a pricing toggle or a carousel is a good island.

Other server-rendered tags stay plain HTML even if an island imports them: only islands come alive in the browser.