Client directive: Viewport

Caution

This library is in beta until releasing the version 1.0.0. It is susceptible to breaking changes as we are polishing the public surface to make it better.

The client:viewport directive hydrates the component when its visible. If the component is visible from start, it will be hydrated.

Note

If you don’t want to use this directive with client:on, it is recommended to use the Astro client:visible directive instead.

Setup

For setting up the directive, include the integration in your Astro project.

1. Install the library using your preferred package manager:

   npm i -D @astro-tools/client-directives

2. Add the integration to your project configuration:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   
   import { viewportClientDirective } from '@astro-tools/client-directives/viewport';
   
   export default defineConfig({
     integrations: [viewportClientDirective()],
   });

With client:on directive

To integrate this directive with the client:on, configure the directive as follows:

astro.config.mjs

import { defineConfig } from 'astro/config';

import { onClientDirective } from '@astro-tools/client-directives/on';

export default defineConfig({
  integrations: [
    onClientDirective({
      directives: [
        {
          name: 'viewport',
          entrypoint: '@astro-tools/client-directives/viewport/directive',
        },
      ],
    }),
  ],
});

Tip

Both integrations, client:on integration and this one, can be included in the project configuration, allowing you to use both directives, client:viewport and client:on="viewport", in your components.

Use

Add the directive as attribute of the component to hydrate when visible:

<MyComponent client:viewport />

This directive is similar to the Astro client:visible directive, but it allows integration with the client:on directive.

Example.astro

---
import Square from '@/libs/examples/Square.svelte';

interface Props {
  id: string;
}

const { id } = Astro.props;
---
<Square {id} text="Click me!" client:viewport />

Square.svelte

<script lang="ts">
import { notifyHydration } from '@/libs/examples/hydration';
import { onMount } from 'svelte';

export let id: string;
export let text: string;

let hydrated = false;

onMount(() => {
  hydrated = true;
  notifyHydration(id);
});
</script>

<button
  type="button"
  class="square"
  class:square--hydrated={hydrated}
  on:click={() => text = 'Clicked!'}>
  {text}
</button>

<style lang="scss">
  @use './Square.scss';
</style>

Preview Static

Click me!