diff --git a/docs/reference/islands.md b/docs/reference/islands.md index 9b1dc2c..f5e7d65 100644 --- a/docs/reference/islands.md +++ b/docs/reference/islands.md @@ -1,6 +1,10 @@ # Islands -To use an interactive React component in your page—any component that responds to user input or has state—you need to wrap it with an ``. +```js +import Island from '@hubspot/cms-components'; +``` + +To use an interactive React component in a page—any component that responds to user input or has state—you need to wrap it with an ``. - Here’s how you do that: When importing the component, add `?island` to the end of the import specifier - Render the Island component from `@hubspot/cms-components`, and pass `InteractiveComponent` from the result of the `?island` import as the `module` prop @@ -8,7 +12,7 @@ To use an interactive React component in your page—any component that responds ```javascript import { useState } from 'react'; -import { Island } from '@hubspot/cms-components'; +import Island from '@hubspot/cms-components'; import InteractiveComponent from '../InteractiveComponent?island'; export default function MyPartial() { @@ -47,32 +51,20 @@ export default function InteractiveComponent({ defaultCount }) { } ``` -## Island props - -### `hydrateOn` - -When rendering a page with Islands on the server the output includes a script to initialize Islands on the client. The default behavior of the island initialization script is to eagerly hydrate all Islands as soon as possible, i.e., on load, but there are other strategies available when hydrating components. - -The available hydration types are: - -- `load` (default) -- `idle` -- `visible` - -These types can be set as the hydrateOn prop on the Island Component, for example: - -```javascript - -``` - -For islands with the `idle` hydration type we use [requestIdleCallback](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback), allowing the hydration to be deferred. This is good for lower priority components, allowing client resources to be used first on higher priority. - -For Islands with the `visible` hydration type we don’t hydrate until the element is visible on screen by using the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API). This mode is good for components that aren't visible to the user immediately, e.g., if they are further down a long page. - -Hydrating means downloading and initializing your Island component code, so using these different hydration types strategically to defer some of that work can help boost initial page load performance! - -### `clientOnly` - -`boolean` - -This is set to `false` by default, but when set to `true` then the Island won’t be rendered on the server. This can be useful for components that rely on logic/libraries that can only run in the browser. +## Island Props + +Name | Type | Default | Description +-- | -- | -- | -- +**clientOnly** | `boolean` | `false` | This is set to `false` by default, but when set to `true` then the Island won’t be rendered on the server. This can be useful for components that rely on logic/libraries that can only run in the browser. +**hydrateOn** | `"load" \| "visible" \| "idle"` | `"load"` | When rendering a page with Islands on the server the output includes a script to initialize Islands on the client. Hydrating means downloading and initializing the Island component code, so using these different hydration types strategically to defer some of that work can help boost initial page load performance! See [Hydration Types](#hydration-types) below for more information. +**id** | `string` | - | This value is passed through to the island's `wrapperTag` id HTML attribute. +**module*** | `React.Component` | - | This can be any React component as long as the import URL for this component includes the `?island` query parameter. Refer to the `InteractiveComponent` example at the top of the docs. +**Wrapper** | `React.Component` | - | If the default `div` or `wrapperTag` prop is not sufficient, you can pass a custom component to be used as the island's wrapper component. +**wrapperClassName** | `string` | - | This value gets passed through to the wrapper component of the island, whether that be the default `div` or a custom tag/component provided by the `wrapperTag` or `Wrapper` component props. +**wrapperStyle** | `CSSProperties` | - | The `CSSProperties` provided will be applied inline to the `wrapperTag` of the island. +**wrapperTag** | `string `| `"div"` | The string provided must be a valid HTML element tag (e.g. 'span', 'article', 'section', etc). + +### [Hydration Types](#hydration-types) +The default behavior of the island initialization script is to eagerly hydrate all Islands as soon as possible, i.e., on `load`, but there are other strategies available when hydrating components: +- For islands with the `idle` hydration type we use [requestIdleCallback](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback), allowing the hydration to be deferred. This is good for lower priority components, allowing client resources to be used first on higher priority. +- For Islands with the `visible` hydration type we don’t hydrate until the element is visible on screen by using the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API). This mode is good for components that aren't visible to the user immediately, e.g., if they are further down a long page.