<NuxtIsland>

Source
Nuxt provides the <NuxtIsland> component to render a non-interactive component without any client JS.

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 : Name of the component to render.
    • type: string
    • required
  • lazy: Make the component non-blocking.
    • type: boolean
    • default: false
  • props: Props to send to the component to render.
    • type: Record<string, any>
  • source: Remote source to call the island to render.
    • type: string
  • dangerouslyLoadClientComponents: Required to load client components from a remote source.
    • type: boolean
    • default: false
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.
Component props and context are sent as GET query parameters to enable caching. Query parameters may be visible in server access logs, CDN caches, and HTTP Referer headers.
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" />.

Known Limitations

useId in island and server components

Each island is rendered in its own Vue app on the server, so Vue's useId counter restarts for every island. Ids generated inside an island can therefore collide with ids generated by other islands on the same page, or by the rest of your app.

Workaround: set a distinct idPrefix on the island's Vue app from a server plugin, based on the island context id:

plugins/island-id-prefix.server.ts
export default defineNuxtPlugin((nuxtApp) => {
  const islandContext = nuxtApp.ssrContext?.islandContext
  if (islandContext) {
    nuxtApp.vueApp.config.idPrefix = `${islandContext.id}-v`
  }
})
  • Identical islands still share the same ids. Two instances of the same island rendered with the same name, props and context share a single server render (and payload entry), so their HTML — including any useId-generated ids — is identical, and the island context id used as prefix is the same. This results in duplicated id attributes in the DOM, which can break aria-* references and <label for> associations between the two instances. There is currently no workaround for this case.
  • useId does not work in interactive components inside islands. A component loaded with the nuxt-client attribute is server-rendered inside the island's app but hydrated by the main client app, so useId returns different values on the server and on the client, causing a hydration mismatch.

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.

Ref

  • refresh()
    • type: () => Promise<void>
    • description: force refetch the server component by refetching it.

Events

  • error
    • parameters:
      • error:
        • type: unknown
    • description: emitted when NuxtIsland fails to fetch the new island.