michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve wording in documentation for client:* directives (#2232)

Browse source 
* Make wording around `client:*` directives more clear

A friend and I both found the wording on this page to be a touch ambiguous. When does the renderer JS download? Does Astro really delay all JS downloading until the component is ready to be hydrated, or just the component JS?

I think these changes make the behavior crystal clear?

* Make tense consistent for `client:only`
This commit is contained in:
Alan 2021-12-21 09:16:34 -08:00 committed by GitHub
parent 9aff6eee71
commit 1b418a6481
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 8 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
docs/src/pages/core-concepts/component-hydration.md
View file

@ -62,29 +62,31 @@ Astro renders every component on the server **at build time**, unless [client:on
import MyReactComponent from '../components/MyReactComponent.jsx';
---
<!-- "client:visible" means the component won't load any client-side
JavaScript until it becomes visible in the user's browser. -->
JavaScript for the component until it becomes visible in the
user's browser. -->
<MyReactComponent client:visible />
```
Note that the renderer JS (e.g. React) and the component's CSS are downloaded with the page. The `client:*` directives only dictate when the component JS is imported and when the component is hydrated.
### `<MyComponent client:load />`
Hydrate the component on page load.
Start importing the component JS at page load. Hydrate the component when import completes.
### `<MyComponent client:idle />`
Hydrate the component as soon as main thread is free (uses [requestIdleCallback()][mdn-ric]).
Start importing the component JS as soon as main thread is free (uses [requestIdleCallback()][mdn-ric]). Hydrate the component when import completes.
### `<MyComponent client:visible />`
Hydrate the component as soon as the element enters the viewport (uses [IntersectionObserver][mdn-io]). Useful for content lower down on the page.
Start importing the component JS as soon as the element enters the viewport (uses [IntersectionObserver][mdn-io]). Hydrate the component when import completes. Useful for content lower down on the page.
### `<MyComponent client:media={QUERY} />`
Hydrate the component as soon as the browser matches the given media query (uses [matchMedia][mdn-mm]). Useful for sidebar toggles, or other elements that should only display on mobile or desktop devices.
Start importing the component JS as soon as the browser matches the given media query (uses [matchMedia][mdn-mm]). Hydrate the component when import completes. Useful for sidebar toggles, or other elements that should only display on mobile or desktop devices.
### `<MyComponent client:only />`
Hydrates the component at page load, similar to `client:load`. The component will be **skipped** at build time, useful for components that are entirely dependent on client-side APIs. This is best avoided unless absolutely needed, in most cases it is best to render placeholder content on the server and delay any browser API calls until the component hydrates in the browser.
Start importing the component JS at page load and hydrate when the import completes, similar to `client:load`. The component will be **skipped** at build time, useful for components that are entirely dependent on client-side APIs. This is best avoided unless absolutely needed, in most cases it is best to render placeholder content on the server and delay any browser API calls until the component hydrates in the browser.
If more than one renderer is included in the Astro [config](/reference/configuration-reference), `client:only` needs a hint to know which renderer to use for the component. For example, `client:only="react"` would make sure that the component is hydrated in the browser with the React renderer. For custom renderers not provided by `@astrojs`, use the full name of the renderer provided in your Astro config, i.e. `<client:only="my-custom-renderer" />`.