astro-client-interaction 👆

This Astro integration lets you load and hydrate framework components on first interaction by introducing the client:interaction directive.

• Why astro-client-interaction?
• Installation
• Usage
• Troubleshooting
• Contributing
• Changelog

Why astro-client-interaction?

This integration is useful when you have several components that may never be interacted with, and are non-essential to your visitors' experience. Delaying their loading and hydration can help improve the performance of your site by reducing the amount of bandwidth usage and main-thread work that needs to be done on the initial page load.

Installation

Manual Install

First, install the astro-client-interaction package using your package manager. If you're using npm or aren't sure, run this in the terminal:

npm install astro-client-interaction

Then, apply this integration to your astro.config.* file using the integrations property:

  // astro.config.mjs
  import { defineConfig } from 'astro/config';
+ import clienIx from 'astro-client-interaction';

  export default defineConfig({
    // ...
    integrations: [clienIx()],
    //             ^^^^^^^
  });

Usage

Once the integration is installed and added to the configuration file, you can add the client:interaction directive to any component that should only hydrate after the visitor presses a key, clicks or touches any part of the page.

---
import Component from "../components/Counter.jsx"
---
<Component client:interaction />

Interactions may happen while the page is loading. This means that components with the client:interaction directive sometimes get loaded before the ones with the client:idle directive. This behavior becomes problematic if you use directives to designate "priorities" to components. To make sure that client:interaction components are always treated as lower priority than client:idle, you can set the value of client:interaction to "idle".

---
import Component from "../components/Counter.jsx"
---
<Component client:interaction="idle" />

When the "idle" value is set, an interaction will schedule the loading of the component for when the browser is idle, instead of loading it immediately on interaction.

Troubleshooting

For help, check out the Discussions tab on the GitHub repo.

Contributing

This package is maintained by lilnasy independently from Astro. The integration code is located at packages/client-interaction/integration.ts. You're welcome to contribute by submitting an issue or opening a PR!

Changelog

See CHANGELOG.md for a history of changes to this integration.