Learn · Lesson 3 of 6

Your first island

  1. Read
  2. Write
  3. Load later
  4. Run
  5. Quiz
  6. Done

Your first island

Most of a page is static HTML. When one part needs to react to clicks or typing, give that component a <script>: it becomes an island, and only it ships JavaScript.

Read #

An island is rendered to HTML on the server like any component. In the browser its code attaches to that HTML: event handlers and updates are wired to what is already there, and nothing re-renders.

state(initial) makes a value reactive. You read and write it as a plain variable; the compiler turns count++ into an update of exactly the text that shows it.

Write #

Create a counter:

src/components/counter.tscl

tscl
<script>
  let count = state(0)
  const double = derived(() => count * 2)
</script>

<button (click)="count++">Clicked {{ count }} times (double: {{ double }})</button>

Put it on a page:

src/pages/index.tscl

tscl
@import counter from '../components/counter.tscl'

<h1>Hello</h1>
<counter />

Hello

This button is the page's only JavaScript.

Load later #

An island's code loads with the page by default. Wait until it's needed instead:

tscl
<counter attach="visible" />

attach="idle" waits until the browser has nothing else to do, visible until it scrolls into view, and interaction until someone clicks, types or focuses inside it. A click that arrives before the code is replayed once it attaches.

Run #

Build the site and look at dist/client: the page's HTML has the button already rendered, and the only script besides the small loader is the counter's.

sh
pnpm vite build

Quiz #

Which components ship JavaScript to the browser?

Show the answer

Answer: Only components with a <script>

A component without a <script> is HTML only. Adding a <script> makes it an island, and only islands ship code.

Done #

You made an island and chose when it loads. Next: pages with their own URLs and data.

In the docs: Islands, State, Lazy attach.