- React
- Next.js
- TypeScript
Using Hygular with React and Next.js: Hooks, Refs, and Cleanup
Set up Hygular CSS and React hooks in Next.js, type element refs correctly, and keep DOM initialization within the component lifecycle.
React owns the rendered tree. A UI runtime may also need DOM listeners, measurements, and temporary elements. A reliable integration makes ownership explicit: setup happens after an element mounts, and cleanup happens when its owner unmounts.
Hygular exposes React hooks through @hygular/core/react. There is no required Hygular provider. Use the hook that matches the interaction instead of initializing the entire runtime inside every component.
Load the stylesheet once
Install the core package in an existing Next.js application:
npm install @hygular/[email protected]
Import its stylesheet in your root layout. Merge this import into your existing layout rather than replacing application metadata or providers:
import '@hygular/core/css';
import type { ReactNode } from 'react';
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}
Global CSS and interactive behavior are separate decisions. A page can use Hygular styles without mounting a JavaScript component.
Type refs for the element receiving them
A tooltip hook returns a ref. In TypeScript, specify the concrete element type when attaching it to a button:
'use client';
import { useTooltip } from '@hygular/core/react';
export function HelpButton() {
const ref = useTooltip<HTMLButtonElement>({
message: 'Changes are saved to this project.',
});
return (
<button ref={ref} type="button" className="button is-ghost">
How saving works
</button>
);
}
Without the generic, the default ref type is HTMLElement. That broader type is not assignable to every element-specific React ref. HTMLButtonElement makes the target match the JSX element without a type assertion.
The tooltip hook sets up its instance in an effect and disposes it during cleanup. In this beta, its options are read during setup; changing the options object on a later render does not automatically reconfigure the existing tooltip.
Some hooks return methods instead of refs
A toast is created when an action needs feedback, so its hook exposes methods:
'use client';
import { useToast } from '@hygular/core/react';
export function NotificationExample() {
const toast = useToast();
return (
<button
type="button"
className="button is-primary"
onClick={() => toast.success('This is a notification preview.')}
>
Preview notification
</button>
);
}
For a real save operation, show success after the request succeeds. A notification should report application state, not substitute for it.
Bind delegated interactions once
Delegated hooks such as useCollapse() bind interaction handlers rather than returning an element ref. Mount them in a stable owner for the relevant interface:
'use client';
import { useCollapse } from '@hygular/core/react';
export function ShippingDetails() {
useCollapse();
return (
<>
<button
type="button"
className="button"
data-hygular-toggle="collapse"
data-target="#shipping-details"
aria-controls="shipping-details"
>
Shipping details
</button>
<div id="shipping-details" className="collapse">
Orders ship within two business days.
</div>
</>
);
}
This example assumes one instance with that ID. In a repeated component, give each target a unique ID and matching selector. In a larger application, mount the delegated hook once in the shell instead of in every repeated item.
Give each element one lifecycle owner
Do not initialize the same element through both a React hook and a global runtime observer. Choose one ownership path. For conditionally visible content, mount a child component that owns the hook together with its target element; an effect that ran while its target was absent cannot bind an element retroactively.
Module imports are designed to tolerate server environments, but DOM setup belongs on the client. A successful server render also does not replace browser interaction tests. Exercise navigation, unmounting, keyboard behavior, and React Strict Mode with your actual components.
See React integration for the full hook API and SSR integration for server-rendered applications.