`<is-land>`

A new performance-focused way to add interactive client-side components to your web site.

Or, more technically: a framework independent partial hydration islands architecture implementation.

View the demos
Check out the initial screencast on Eleventy’s YouTube channel and the follow up screencast with more framework examples.
Learn more about Islands Architecture

Features:

Easy to add to existing components
Zero dependencies
Not tightly coupled to a server framework or site generator tool.
Small footprint (5 kB minimized; 1.61 kB with Brotli compression)
Server-rendered (SSR) component examples available for SSR-friendly frameworks (Lit, Svelte, Vue, Preact are provided)

Examples for:

Web Components
Web Components using Declarative Shadow DOM (New in v3.0.0)
Svelte (and SSR)
Vue (and petite-vue) (and SSR)
Preact (and SSR)
Lit (and SSR)
Alpine.js
Embedded in Markdown
defer-hydration Component Attribute Support (New in v3.0.0) (Read more about defer-hydration at zachleat.com)
Experimental: Image Loading
Experimental: Using import maps to simplify import URLs. This is for-future-reference when browser support broadens.

Integrations in the wild:

Installation

npm install @11ty/is-land

Add is-land.js to your primary bundle. It can be deferred and/or loaded asynchronously.

When using with web components it must be the first custom element defined (via customElements.define) on the page. Choose your style:

<script type="module" src="/is-land.js"></script>

<script type="module">
import "/is-land.js";
</script>

The framework autoinit examples shown below now require a separate is-land-autoinit.js file too.

Usage

<is-land>This is an island.</is-land>

Add any number of loading conditions to this tag to control how and when the island is initialized. You can mix and match:

on:visible
on:idle
on:interaction (defaults to touchstart,click)
- Change events with on:interaction="mouseenter,focusin"
on:media
- Viewport size: on:media="(min-width: 64em)"
- Reduced motion:
  - Opt-in with on:media="(prefers-reduced-motion)"
  - Opt-out with on:media="(prefers-reduced-motion: no-preference)"
Save Data (read about Save Data on MDN)
- Opt-in with on:save-data
- Opt-out with on:save-data="false"

<is-land on:visible on:idle>
  <!-- your HTML here -->

  <is-land on:media="(min-width: 64em)">
    <!-- Islands can be nested -->
    <!-- Islands inherit all of their parents’ loading conditions -->
  </is-land>
</is-land>

Controlling Fallback Content

Pre-JS

<is-land on:visible on:idle>
  <vanilla-web-component>
    Put your pre-JS fallback content in your web component.
  </vanilla-web-component>
</is-land>

Post-JS with `<template>`

Place any post-JS content inside of one or more <template data-island> elements anywhere in the <is-land>. These will be swapped with their template content. You can nest an <is-land> in there if you want!

<is-land on:visible on:idle>
  <template data-island>
    <vanilla-web-component>
      This component is post-JS.
    </vanilla-web-component>
  </template>
</is-land>

Use data-island="replace" to replace the contents of the <is-land> with the template.
Use data-island="once" to run a template’s contents once per page (keyed from template contents). (New in v2.0.1)

Run your own custom JavaScript, load your own CSS

Embed a script inside the template to run custom JS when the island’s loading conditions have been satisfied!

<is-land on:visible>
  <template data-island>
    <!-- CSS -->
    <style>/* My custom CSS */</style>
    <link rel="stylesheet" href="my-css-file.css">

    <!-- JS -->
    <script type="module">console.log("Hydrating!");</script>
    <script type="module" src="my-js-file.js"></script>
  </template>
</is-land>

You can also use the ready attribute for styling, added to the <is-land> when the island has been hydrated.

<style>
is-land[ready] {
  background-color: lightgreen;
}
</style>

Framework Support

Demos and source in the HTML are available for each framework listed here. These examples require the is-land-autoinit.js JavaScript file (in addition to is-land.js).

`autoinit`

Use the autoinit and import attributes together to import a third party library (or component code). autoinit can be one of petite-vue, vue, preact, or svelte. It is recommended to use a self-hosted framework library (future Eleventy integrations will automate this for you).

<is-land on:visible autoinit="petite-vue" import="https://unpkg.com/petite-vue@0.4.1/dist/petite-vue.es.js" v-scope="{ name: 'post-JS' }">
  Hello from <span v-html="name">pre-JS</span>
</is-land>

<!-- when import maps support is better, this simplifies with an entry for petite-vue in your import map -->
<is-land on:visible import="petite-vue" v-scope="{ name: 'post-JS' }">
  Hello from <span v-html="name">pre-JS</span>
</is-land>

Petite Vue

Small library (8K)
Rendering modes: Client
Progressive-enhancement friendly (full control of fallback content)
Support for autoinit

<is-land on:visible autoinit="petite-vue" import="https://unpkg.com/petite-vue@0.4.1/dist/petite-vue.es.js" v-scope="{ name: 'post-JS' }">
  Hello from <span v-html="name">pre-JS</span>
</is-land>

Vue

Larger library (51 kB)
Rendering modes: Client-only, Server-only, Server + Client (Hydration)
Support for autoinit

<is-land on:visible>
  <div id="vue-app">
    Hello from <span v-html="name">pre-JS</span>
  </div>

  <template data-island>
    <script type="module">
    import { createApp } from "https://unpkg.com/vue@3.2.36/dist/vue.esm-browser.prod.js";

    createApp({
      data: () => ({ name: "post-JS" })
    }).mount("#vue-app")
    </script>
  </template>
</is-land>

Svelte

Smaller library (12 kB)
Rendering modes: Client-only, Server-only, Server + Client (Hydration)
- Requires a compiler for both client and server modes (tighter server coupling)
Support for autoinit

This example uses an Eleventy/Svelte integration to compile a Svelte component.

{% assign component = "./lib/svelte/my-component.svelte" | svelte %}
<is-land on:visible autoinit="svelte" import="{{ component.clientJsUrl }}"></is-land>

Example component code ./lib/svelte/my-component.svelte:

<script>
  // using export to allow overrides via props
  export let name = 'world';

  let count = 0;

  function handleClick() {
    count += 1;
  }
</script>

<style>
  h1 { color: red }
</style>

<h1>Hello {name}</h1>

<button on:click={handleClick}>
  Clicked {count} {count === 1 ? 'time' : 'times'}
</button>

Preact

Very small library (~5 kB)
Rendering modes: Client-only, Server-only, Server + Client (Hydration)
Support for autoinit

This example uses htm instead of JSX.

<is-land on:visible autoinit="preact" import="/lib/preact/preact-component.js"></is-land>

Example component code ./lib/preact/preact-component.js:

import { html, render } from 'https://unpkg.com/htm/preact/index.mjs?module'

function App (props) {
  return html`<p><strong>Hello ${props.name}!</strong></p>`;
}

export default function(el) {
  render(html`<${App} name="from Preact" />`, el);
}

Lit

Small library (~7 kB)
Rendering modes: Client-only, Server + Client (Hydration)
- Note: Server-only is not supported: it requires Declarative Shadow DOM support to work without JS.
No support for autoinit

<is-land on:visible import="./lib/lit/lit-component.js">
  <lit-component name="Post-JS">Pre-JS Content</lit-web-component>
</is-land>

Example component code ./lib/lit/lit-component.js:

import {html, css, LitElement} from "https://cdn.jsdelivr.net/gh/lit/dist@2/core/lit-core.min.js";

customElements.define('lit-component', class extends LitElement {
  static properties = {
    name: {type: String},
  };

  render() {
    return html`<p>Hello, ${this.name || "Stranger"}!</p>`;
  }
});

Alpine.js

Smaller library (15 kB)
Rendering modes: Client-only
No autoinit but it is not needed (functionality included for-free by Alpine.js)

<is-land on:visible import="https://unpkg.com/alpinejs">
  <div x-data="{ count: 0 }">
    Hello from Alpine.js!

    <button @click="count++">⬆️</button> <button @click="count--">⬇️</button> <span x-text="count"></span>
  </div>
</is-land>

11ty/is-land

<is-land>