API Reference

prehydrate(options)

This is the main function. It gives you everything you need to make a component show the right content before React loads.

Parameters

options (PrehydrateOptions<T>) - Required

Configuration options for prehydration.

key (string) - Required

Unique identifier for this prehydration instance. Used to generate the container ID (prehydrate-{key}).

initialState (T | (() => T))

What should users see when the page loads?

• Static value (like 'loading') — Use when you know the value ahead of time
• Function (like () => new Date()) — Use when the value needs to be computed fresh on each page load

The function approach is what makes Prehydrate powerful. () => new Date() runs when the page loads, not when your server builds — so users always see the current time.

deps (DependencyMap)

Helper functions or constants your prehydrated content needs.

deps: {
  formatTime: (d) => d.toLocaleTimeString(),
  TIMEZONE: 'America/New_York',
}

See Dependencies for details.

Returns

An object containing:

Prehydrate (ComponentType<PrehydrateProps>)

Wrap your component with this. It handles all the magic.

<Prehydrate>
  <YourComponent bind={bind} />
</Prehydrate>

bind ((key: string) => Record<string, T | undefined>)

Connects your component's state to the prehydrated value. Use it inside useState:

const [time, setTime] = useState(() => {
  const props = bind('time');
  return props.time || new Date();
});

Example

import { prehydrate } from 'prehydrate';

const { Prehydrate, bind } = prehydrate<Date>({
  key: 'my-clock',
  initialState: () => new Date(),
  deps: {
    formatTime: (d: Date) => d.toLocaleTimeString(),
  },
});

Prehydrate Component

The wrapper component returned by prehydrate(). Put your component inside it.

Props

children (ReactNode) - Required

Your component. Pass bind as a prop so it can use the prehydrated values.

What it does

When the server renders your page, Prehydrate includes a tiny inline script. This script runs the instant the browser parses it — before React even starts downloading — and updates the content to show the correct values.

Example

<Prehydrate>
  <Clock bind={bind} />
</Prehydrate>

bind(key)

Connects your component to the prehydrated state. Call it inside useState.

Parameters

key (string) - Required

A name for this piece of state. Use the same name when accessing the returned object.

Returns

An object containing your prehydrated value. When React loads, it returns an empty object — but by then the DOM already shows the correct content, so users don't see any change.

Usage Pattern

Always use bind() inside a lazy useState initializer:

const [time, setTime] = useState(() => {
  const boundProps = bind('time');
  return boundProps.time || new Date(); // Fallback for SSR
});

Types

PrehydrateOptions<T>

interface PrehydrateOptions<T = unknown> {
  key: string;
  initialState?: T | (() => T);
  deps?: DependencyMap;
}

PrehydrateResult<T>

interface PrehydrateResult<T = unknown> {
  Prehydrate: ComponentType<PrehydrateProps>;
  bind: (key: string) => Record<string, T | undefined>;
}

PrehydrateProps

interface PrehydrateProps {
  children: ReactNode;
}

DependencyMap

type DependencyMap = Record<string, unknown>;

Events

prehydration-complete

A custom event dispatched on window when prehydration finishes.

window.addEventListener('prehydration-complete', () => {
  console.log('DOM updated with prehydrated values');
});

This event fires after the inline script has replaced the SSR content with the prehydrated content.