Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Display

Island

A rounded floating panel that springs between a compact and an expanded live-activity state.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Morning Light

Ana Martins

Hidden

Install

Run in your project
bunx --bun @getweini/cli@latest add island

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Morning Light

Ana Martins

Vue
<script setup lang="ts">
import Island from './components/ui/island/Island.vue'
</script>

<template>
  <Island>
    <span class="flex-1 truncate">Now playing</span>
    <span class="text-xs opacity-70">2:14</span>
    <template #expanded>
      <p class="font-medium">Morning Light</p>
      <p class="opacity-70">Ana Martins</p>
    </template>
  </Island>
</template>

The default slot is the compact toggle content. The expanded slot appears when the island grows.

When to use it

Live activities

Show a timer, delivery, or playback status that can reveal details on demand.

Transient status

Keep a small floating status visible without taking over the page.

More examples

Controlled state

Use v-model:expanded when another control or event also opens the island.

Controlled state
<script setup lang="ts">
import { ref } from 'vue'
import Island from './components/ui/island/Island.vue'

const expanded = ref(false)
</script>

<template>
  <div class="grid gap-3">
    <Island v-model:expanded="expanded">
      <span class="flex-1 truncate">Order on the way</span>
      <span class="text-xs opacity-70">8 min</span>
      <template #expanded>
        <p>Your courier is two streets away.</p>
      </template>
    </Island>
    <p class="text-center text-sm text-muted-foreground">
      {{ expanded ? 'Expanded' : 'Compact' }}
    </p>
  </div>
</template>

Wider expanded size

Set --ui-island-expanded-size or --ui-island-compact-size on the root to change the widths.

Wider expanded size
<script setup lang="ts">
import Island from './components/ui/island/Island.vue'
</script>

<template>
  <Island default-expanded style="--ui-island-expanded-size: 26rem">
    <span class="flex-1 truncate">Upload in progress</span>
    <span class="text-xs opacity-70">64%</span>
    <template #expanded>
      <p>report-final.pdf</p>
      <p class="opacity-70">12 of 19 MB sent</p>
    </template>
  </Island>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Island

Complete API for Island
NameType or signatureDefaultWhat it does
expandedmodelboolean | undefinedNot setControlled expanded state. Supplying the prop, even as `false`, makes the parent authoritative.
defaultExpandedpropboolean | undefinedfalseInitial expanded state when `expanded` is not supplied.
disabledpropboolean | undefinedfalsePrevent interaction and show the disabled state.
update:expandedevent[expanded: boolean]—Requests a new expanded value from the parent.
defaultslot(props: { expanded: boolean; }) => unknownRequiredContent shown inside Island.
expandedslot((props: { expanded: boolean; }) => unknown) | undefinedOptionalContent for the expanded area of Island.
expandexposed() => void—Access expand from a component template ref.
collapseexposed() => void—Access collapse from a component template ref.
toggleexposed() => void—Access toggle from a component template ref.
focusexposed() => void | undefined—Move keyboard focus to this control.
Public type definitions
Public types
// packages/frameworks/vue/components/island/types.ts
// ------- TYPES -------

export interface IslandProps {
  /** Controlled expanded state. Supplying the prop, even as `false`, makes the parent authoritative. */
  expanded?: boolean
  /** Initial expanded state when `expanded` is not supplied. */
  defaultExpanded?: boolean
  disabled?: boolean
}

Implementation notes

  • Keep compact content phrasing-only: it lives inside a native button.
  • Without an expanded slot the island is a static panel and the button has no expanded state.
  • Springs apply to the island's own size; collapse uses a soft spring that never bounces wildly.

Accessibility and localization

  • The toggle exposes aria-expanded and aria-controls; the expanded content is a named region and is inert while collapsed.
  • Escape collapses the island and returns focus to the toggle.
  • All text comes from your slots; the component adds no copy.
  • Motion stops under reduced motion.

Source contract and editing guidance