From 586e1ba3ee8c788a5fb6eb03221960c43dbc347b Mon Sep 17 00:00:00 2001
From: Julien Huang <julien.huang@outlook.fr>
Date: Wed, 2 Aug 2023 09:31:22 +0200
Subject: [PATCH] docs: document `NuxtIsland` (#22434)

---
 docs/3.api/2.components/8.nuxt-island.md      | 50 +++++++++++++++++++
 .../{8.teleports.md => 9.teleports.md}        |  0
 2 files changed, 50 insertions(+)
 create mode 100644 docs/3.api/2.components/8.nuxt-island.md
 rename docs/3.api/2.components/{8.teleports.md => 9.teleports.md} (100%)

diff --git a/docs/3.api/2.components/8.nuxt-island.md b/docs/3.api/2.components/8.nuxt-island.md
new file mode 100644
index 0000000000..6368506ec1
--- /dev/null
+++ b/docs/3.api/2.components/8.nuxt-island.md
@@ -0,0 +1,50 @@
+---
+title: "<NuxtIsland>"
+description: "Nuxt provides `<NuxtIsland>` component to render a non-interactive component without any client JS"
+---
+
+# `<NuxtIsland>`
+
+Nuxt provide `<NuxtIsland>` to render components only server side.
+
+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.
+
+::alert{type=warning}
+This component is experimental and in order to use it you must enable the `experimental.componentsIsland` option in your `nuxt.config`.
+::
+
+::alert{type=info}
+Global styles of your application are sent with the response
+::
+
+::alert{type=info}
+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`
+
+::alert{type=warning}
+Remote islands need `experimental.componentsIsland` to be `'local+remote'` in your `nuxt.config`.
+::
+
+## `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.
diff --git a/docs/3.api/2.components/8.teleports.md b/docs/3.api/2.components/9.teleports.md
similarity index 100%
rename from docs/3.api/2.components/8.teleports.md
rename to docs/3.api/2.components/9.teleports.md