---
metaTitle: Island component | AwesCode UI
meta:
  - name: description
    content: The <AwIsland /> component provides a card-based container with icon, title, description, and collapsible content - UI Vue component for AwesCode UI.
title: Island
---

# AwIsland

**Category:** Molecule | **Import:** Global

The `AwIsland` component is an enhanced card component that displays content with an icon, title, description, and optional collapsible content section. It's designed for feature showcases, settings panels, and informational blocks.

## Overview

`AwIsland` provides an island-style card with:
- Icon with customizable color
- Title and description
- Collapsible/expandable content
- Options slot for action buttons
- Footer section
- Custom arrow icon
- Can be used as a link
- Responsive design

## Usage

### Basic Example

```markup
<AwIsland
  title="Feature Title"
  description="This is a description of the feature"
  icon="awesio/settings"
  icon-color="accent"
>
  <p>Content goes here</p>
</AwIsland>
```

### Collapsible Content

```markup
<AwIsland
  title="Collapsible Section"
  description="Click to expand"
  icon="awesio/info-circle"
>
  <div>
    <p>This content can be collapsed and expanded.</p>
    <p>Add any content here.</p>
  </div>
</AwIsland>
```

### Always Expanded

```markup
<AwIsland
  title="Always Open"
  description="This section is always visible"
  icon="awesio/check"
  expanded
>
  <p>Content is always visible.</p>
</AwIsland>
```

### As Link

```markup
<AwIsland
  title="Clickable Island"
  description="Click anywhere to navigate"
  icon="awesio/arrow-r"
  tag="AwLink"
  href="/settings"
/>
```

### With Options

```markup
<AwIsland
  title="With Actions"
  description="Section with action buttons"
  icon="awesio/settings"
  expanded
>
  <template #options>
    <AwButton size="sm" icon="awesio/edit" theme="icon" />
    <AwButton size="sm" icon="awesio/delete" theme="icon" />
  </template>

  <p>Content with actions</p>
</AwIsland>
```

**Note:** The options slot is usually used with the `expanded` prop to keep the content visible while providing action buttons.

### With Custom Icon

You can use the `icon` slot to replace the default icon with custom content, such as images or avatar components.

**Using Custom Image:**

```markup
<AwIsland title="Custom Icon" description="Using slot for custom icon">
  <template #icon>
    <img src="/custom-icon.svg" class="w-6 h-6" />
  </template>

  <p>Content</p>
</AwIsland>
```

**Using AwAvatar Component:**

```markup
<AwIsland
  title="Personal Information"
  description="Your personal details"
  :model="personalModel"
>
  <template #icon>
    <AwAvatar
      :src="personalModel.$.avatar"
      :name="personalModel.$.name"
      :size="42"
    />
  </template>

  <AwGrid>
    <AwInput v-model="personalModel.name" label="Name" />
    <AwInput v-model="personalModel.email" label="Email" />
  </AwGrid>
</AwIsland>
```

This pattern is commonly used for user profile sections where an avatar provides better visual representation than an icon.

### With Footer

```markup
<AwIsland
  title="With Footer"
  description="Island with footer section"
  icon="awesio/check"
>
  <p>Main content</p>

  <template #footer>
    <AwButton>Save Changes</AwButton>
  </template>
</AwIsland>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| title | Island title | `String` | `false` | `''` |
| titleTag | HTML tag for title | `String` | `false` | `'h2'` |
| description | Description text below title | `String` | `false` | `''` |
| icon | Icon name - see [Built-in Icons](/reference/icons) | `String` | `false` | `''` |
| iconColor | Icon color (CSS custom property name) | `String` | `false` | `'mono-400'` |
| expanded | Always show content (not collapsible) | `Boolean` | `false` | `false` |
| show | Initial collapsed state | `Boolean` | `false` | `false` |
| showArrow | Force show arrow icon | `Boolean` | `false` | `false` |
| tag | Root element tag (use 'AwLink' for links) | `String` | `false` | `'section'` |
| model | vue-mc Model instance for save/reset functionality | `Object` | `false` | `null` |
| disabled | Disable island interactions | `Boolean` | `false` | `false` |

All AwCard props are also supported (inherited).

**Model Object Requirements:**

When providing a `model` prop, the object must implement:
- `changed()` - Method that returns `true` if model has unsaved changes
- `save()` - Method that returns a Promise to save changes
- `reset()` - Method to reset changes to original values

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| default | Main content | `{ isOpened, toggle }` | - |
| icon | Custom icon | - | AwIcon with icon prop |
| title | Custom title | `{ titleTag, isOpened, toggle }` | Title text |
| after-title | Content after title | - | - |
| description | Custom description | `{ isOpened, toggle }` | AwDescription with description prop |
| options | Action buttons before arrow | `{ isOpened, toggle }` | - |
| arrow | Custom arrow icon | `{ isOpened, toggle }` | AwIconSystemMono angle |
| separator | Content between header and body | `{ isOpened, toggle }` | - |
| footer | Footer section | `{ isOpened, toggle }` | - |

### Events

Inherits all events from AwCard.

### Methods

| Name | Parameters | Description |
|------|------------|-------------|
| toggle | - | Toggle collapsed/expanded state |

## Behavior

### Collapsible Mode (default)

When content slot is present and `expanded` is false:
- Arrow icon shows collapse/expand state
- Click header to toggle content
- Content animated with AwAccordionFold
- isOpened state tracked internally

### Expanded Mode

When `expanded` prop is true:
- Content always visible
- No collapse animation
- Arrow icon rotates 180° (pointing down)
- Header not clickable for toggle

**Common Pattern with Options Slot:**

The `expanded` prop is commonly used together with the `options` slot to create always-visible panels with action buttons:

```markup
<AwIsland
  title="User Settings"
  description="Manage your preferences"
  icon="awesio/settings"
  expanded
>
  <template #options>
    <AwButton size="sm" icon="awesio/edit" theme="icon" />
    <AwButton size="sm" icon="awesio/delete" theme="icon" />
  </template>

  <p>Settings content here</p>
</AwIsland>
```

This pattern ensures the content remains visible while users interact with the action buttons, avoiding the need to expand/collapse to access both content and actions.

### Link Mode

When `tag="AwLink"`:
- Entire island becomes clickable link
- Inherits all AwLink props (href, to, etc.)
- Card reset styling applied

## Model Integration

### Using with vue-mc Models

`AwIsland` integrates with vue-mc models to provide automatic save/reset functionality in the footer. When a model is provided and has unsaved changes, the footer automatically displays Save and Reset buttons.

```javascript
import { BaseModel } from '@awes-io/vue-mc'

class SettingsModel extends BaseModel {
    defaults() {
        return {
            notifications: true,
            darkMode: false
        }
    }

    routes() {
        return {
            save: '/api/settings'
        }
    }
}

export default {
    data() {
        return {
            settingsModel: new SettingsModel()
        }
    }
}
```

```markup
<AwIsland
  title="Settings"
  description="Configure your preferences"
  icon="awesio/settings"
  :model="settingsModel"
>
  <AwGrid>
    <AwCheckbox v-model="settingsModel.notifications" label="Enable notifications" />
    <AwCheckbox v-model="settingsModel.darkMode" label="Dark mode" />
  </AwGrid>
</AwIsland>
```

**Automatic Behavior:**

- **No Changes**: Footer shows only "Close" button
- **Has Changes**: Footer shows "Reset" and "Save" buttons
- **Saving**: Save button disabled during save operation
- **Success**: Shows success notification and closes island
- **Error**: Shows error notification and keeps island open

### Custom Footer with Model

You can override the default footer buttons while still using model integration:

```markup
<AwIsland
  title="Settings"
  :model="settingsModel"
>
  <AwCheckbox v-model="settingsModel.notifications" label="Notifications" />

  <template #buttons>
    <AwButton
      v-if="settingsModel.changed()"
      @click="settingsModel.reset()"
      color="mono"
    >
      Cancel
    </AwButton>
    <AwButton
      v-if="settingsModel.changed()"
      @click="customSave"
      :disabled="settingsModel.saving"
    >
      Apply Changes
    </AwButton>
  </template>
</AwIsland>
```

## AwIslandBuilder

### Overview

`AwIslandBuilder` is a wrapper component that manages multiple `AwIsland` components with accordion behavior. Only one island can be open at a time, and it provides unsaved changes protection when switching between islands.

### Basic Usage

```markup
<AwIslandBuilder>
  <AwIsland
    title="Personal Information"
    description="Your personal details"
    icon="awesio/user"
    :model="personalModel"
  >
    <AwInput v-model="personalModel.name" label="Name" />
    <AwInput v-model="personalModel.email" label="Email" />
  </AwIsland>

  <AwIsland
    title="Account Settings"
    description="Manage your preferences"
    icon="awesio/settings"
    :model="accountModel"
  >
    <AwCheckbox v-model="accountModel.notifications" label="Email notifications" />
    <AwCheckbox v-model="accountModel.twoFactor" label="Two-factor authentication" />
  </AwIsland>

  <AwIsland
    title="Privacy"
    description="Control your privacy"
    icon="awesio/lock"
    :model="privacyModel"
  >
    <AwCheckbox v-model="privacyModel.publicProfile" label="Public profile" />
    <AwCheckbox v-model="privacyModel.showEmail" label="Show email" />
  </AwIsland>
</AwIslandBuilder>
```

### AwIslandBuilder Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| confirmText | Confirmation message for unsaved changes | `String` | `false` | `'There is unsaved data...'` |

All `AwGrid` props are also supported (inherited).

### Accordion Behavior

**Single Open Island:**
- Only one island can be expanded at a time
- Clicking an island header collapses the currently open island
- Click the same header again to collapse it

**Unsaved Changes Protection:**

When switching islands with unsaved changes:
1. Confirmation dialog appears
2. User can confirm (discards changes) or cancel (stays on current island)
3. If confirmed, model is reset and new island opens

**Route Navigation Protection:**

Automatically prevents navigation with unsaved changes:
- Intercepts router navigation
- Shows confirmation dialog
- Resets model if user confirms
- Cancels navigation if user declines

**Window Close Protection:**

Prevents accidental window close with unsaved changes:
- Browser shows native "Leave site?" dialog
- Uses `confirmText` prop as message (where supported)

### Use Cases

**Settings Pages:**
Perfect for grouped settings with separate save contexts:

```markup
<AwIslandBuilder>
  <AwIsland title="Profile" :model="profileModel">...</AwIsland>
  <AwIsland title="Security" :model="securityModel">...</AwIsland>
  <AwIsland title="Notifications" :model="notificationsModel">...</AwIsland>
</AwIslandBuilder>
```

**Wizard Steps:**
Multi-step forms with independent save operations:

```markup
<AwIslandBuilder>
  <AwIsland title="Step 1: Basic Info" :model="step1Model">...</AwIsland>
  <AwIsland title="Step 2: Details" :model="step2Model">...</AwIsland>
  <AwIsland title="Step 3: Review" :model="step3Model">...</AwIsland>
</AwIslandBuilder>
```

**Expandable Sections:**
Read-only information sections (without models):

```markup
<AwIslandBuilder>
  <AwIsland title="Documentation">
    <p>Documentation content...</p>
  </AwIsland>
  <AwIsland title="Examples">
    <p>Example code...</p>
  </AwIsland>
</AwIslandBuilder>
```

## Icon Colors

Use CSS custom property names for icon colors:

```markup
<AwIsland
  icon="awesio/info-circle"
  icon-color="accent"
/>

<AwIsland
  icon="awesio/warning"
  icon-color="error"
/>

<AwIsland
  icon="awesio/check"
  icon-color="success"
/>
```

## Related Components

- `AwIslandBuilder` - Accordion wrapper for multiple islands
- `AwCard` - Base card component
- `AwAccordionFold` - Collapse animation (used internally)
- `AwIcon` - Icon component
- `AwIconSystemMono` - System icons
- `AwAvatar` - Avatar component (can be used in icon slot)
- `AwIslandAvatar` - Island variant with avatar
- [vue-mc Models](/vue-mc/models) - Model integration documentation

## Notes

- **Import Method:** Global - Available as molecule component
- Extends AwCard component
- Uses AwAccordionFold for collapse animation
- Arrow icon automatically appears when content slot is used
- Click anywhere in header to toggle (when collapsible)
- Icon color uses CSS custom properties (--c-{color})
- Content toggle only works when `expanded` is false
- Title slot provides titleTag for custom heading levels
- Icon slot can be used with AwAvatar for user profile sections
- Options slot appears before arrow icon
- Footer only visible when footer slot is used
- Model prop enables automatic save/reset functionality
- Works seamlessly with vue-mc BaseModel instances
- AwIslandBuilder provides accordion behavior for multiple islands
- Builder automatically handles unsaved changes protection