Skip to main content
When rendering an island component, the content of the island component is static, thus no JS is downloaded client-side. Changing the island component props triggers a refetch of the island component to re-render it again.
Global styles of your application are sent with the response.
Server only components use <NuxtIsland> under the hood

​
Props

​
name
string
required
Name of the component to render.
By default, component islands are scanned from the ~/components/islands/ directory. So the ~/components/islands/MyIsland.vue component could be rendered with <NuxtIsland name="MyIsland" />.
​
lazy
boolean
default:"false"
Make the component non-blocking.
​
props
Record<string, any>
Props to send to the component to render.
​
source
string
Remote source to call the island to render.
Remote islands need experimental.componentIslands to be 'local+remote' in your nuxt.config.
Using the source prop to render content from a remote server is inherently dangerous. When you specify a remote source, you are fully trusting that server to provide safe HTML content that will be rendered directly in your application.This is similar to using v-html with external content - the remote server can inject any HTML, including potentially malicious content. Only use source with servers you fully trust and control.The dangerouslyLoadClientComponents prop controls an additional layer of risk: whether to also download and execute client components from the remote source. Even with dangerouslyLoadClientComponents disabled (the default), you are still trusting the remote server’s HTML output.
​
dangerouslyLoadClientComponents
boolean
default:"false"
Required to load client components from a remote source.

​
Slots

Slots can be passed to an island component if declared. Every slot is interactive since the parent component is the one providing it. Some slots are reserved to NuxtIsland for special cases.

​
#fallback

Specify the content to be rendered before the island loads (if the component is lazy) or if NuxtIsland fails to fetch the component. 
<template>
  <NuxtIsland name="MyIsland" lazy>
    <template #fallback>
      <p>Loading island...</p>
    </template>
  </NuxtIsland>
</template>

​
Methods

​
refresh()

Force refetch the server component by refetching it. Type: () => Promise<void> 
<template>
  <NuxtIsland ref="island" name="MyIsland" />
</template>

<script setup lang="ts">
const island = ref()

// Manually refresh the island
await island.value.refresh()
</script>

​
Events

​
@error

Emitted when NuxtIsland fails to fetch the new island. Parameters:
  • error (type: unknown) - The error that occurred during fetching.
<template>
  <NuxtIsland name="MyIsland" @error="handleError" />
</template>

<script setup lang="ts">
const handleError = (error: unknown) => {
  console.error('Island failed to load:', error)
}
</script>