Toaster props

<Toaster> renders the stack and the Island of the controller its <CloudletProvider> supplies. It has no controller prop. This page lists every prop and says when it is read: on every render, or once when the Toaster attaches to the controller after mount. A prop read on attach changes only after a remount, for example with a new key.

import { CloudletProvider, createCloudlet, Toaster } from '@cloudlet/toast';

const cloudlet = createCloudlet();

export function App({ nonce }: { nonce: string }) {
  return (
    <CloudletProvider controller={cloudlet}>
      <Toaster position="auto" theme="system" offsets={{ obstruction: { bottom: 46 } }} nonce={nonce} />
    </CloudletProvider>
  );
}

Props

ToasterProps, every prop optional.

The Toaster attaches after mount, so the server render and the first hydration render are empty. Unmounting it detaches: visible time pauses and every notification and operation stays with the controller, ready for the next Toaster. One controller is shown by one Toaster at a time.

ToasterOffsets

Distance from each screen edge is safe-area inset + gutter + obstruction, in CSS pixels, on physical edges: left stays left in RTL.

EdgeInsets:

Do not add the keyboard's height: the stack already stays inside the visual viewport. Positioning & offsets explains the formula.

ToasterAttention

ToasterMotion

CloudletMotionOverrides is a partial CloudletMotionConstants, and a nested spring may be partial too: { slide: { damping: 30 } }. A new object is read again; the same object is not. The current values live in packages/cloudlet/src/react/motion.ts.

CloudletSpring is a physical spring, CloudletTimedSpring a spring defined by time:

CloudletMotionConstants: durations in milliseconds at timeScale: 1, offsets and blur in CSS pixels.

classNames

classNames adds your classes next to the own cloudlet-* class of each part; it never replaces it. Empty and non-string values are ignored. Theming with CSS tokens is on Styling & strict CSP.

CloudletProvider

<CloudletProvider controller={cloudlet}> makes a controller available to useCloudlet, useOptionalCloudlet and <Toaster> below it. It only supplies the instance: it never creates a controller and never disposes it.

The controller may be null while it does not exist yet, for example when an effect creates it: the server render and the first client render then have no controller. Under a null controller <Toaster> renders nothing and useOptionalCloudlet() returns null, so your children can render on the server. See SSR & Next.js.

CloudletProviderProps:

useCloudlet

useCloudlet() returns the ReactCloudletController of the nearest CloudletProvider. Outside a provider, or while the provider's controller is null, it throws an Error that says so.

import { useCloudlet } from '@cloudlet/toast';

export function SaveButton() {
  const cloudlet = useCloudlet();
  return <button onClick={() => cloudlet.show({ title: 'Saved', kind: 'success' })}>Save</button>;
}

useOptionalCloudlet

useOptionalCloudlet() returns the controller of the nearest CloudletProvider, or null outside a provider and while its controller is null. Use it in components that also render before the controller exists, such as on the server.

import { useOptionalCloudlet } from '@cloudlet/toast';

export function SaveButton() {
  const cloudlet = useOptionalCloudlet();
  return (
    <button disabled={!cloudlet} onClick={() => cloudlet?.show({ title: 'Saved', kind: 'success' })}>
      Save
    </button>
  );
}

The signatures of the React exports are also exported as types: CloudletProviderComponent, UseCloudlet, UseOptionalCloudlet and ToasterComponent.