Install: React, Next.js, Fumadocs and plain HTML

The widget is a web component (<suo-search>) with a thin React wrapper. Every install method loads the same underlying widget — pick the tab that matches your stack. React, Next.js and Fumadocs all start with the package:

npm install @suo/react

<script src="https://cdn.usesuo.com/widget@0.js" async></script>
<suo-search host="https://api.usesuo.com" api-key="suo_search_YOUR_KEY" index-name="docs"></suo-search>

Notes per framework

HTML. widget@0.js is an auto-updating alias with no integrity hash. Pin an exact version with Subresource Integrity if your deployment requires it — see "Pin a version" below. If your site sends a Content Security Policy, see Content security policy for the origins to allow.

React. @suo/react is a client-only wrapper — render it inside a component your framework does not server-render, or guard it behind a mount check if your setup requires that explicitly.

Next.js. Mark the component 'use client' in the App Router.

Fumadocs. Fumadocs renders search through a SearchDialog component you supply to RootProvider, not a plain child, so the snippet wraps <SuoSearch> in one. This site (apps/docs) does exactly this for its own search, including the escape-to-close and focus handling a real dialog needs — see app/components/suo-search-dialog.tsx and app/routes/site.tsx for the full wiring.

Attributes shared by every install

See the full widget reference for every attribute and method.

Recent searches live in the visitor's browser

The widget keeps each visitor's recent searches and recently viewed results in localStorage, scoped to your index name, so it can show them again on their next visit. Nothing here is sent to suo or to your own servers — it never leaves the visitor's browser. If you publish a privacy policy for your own site or app, mention that recent search terms are stored locally in the visitor's browser.

Pin a version

For a deployment that needs Subresource Integrity or a frozen widget version:

<script
	src="https://cdn.usesuo.com/widget@0.0.1.js"
	integrity="sha384-…"
	crossorigin="anonymous"
	async
></script>

Exact versions are retained on the CDN indefinitely; the @0 alias always points at the newest 0.x release. The widget is still before 1.0, so a 0.x release can change behaviour: pin an exact version if that matters to your site. When 1.0 ships it gets a new alias, and @0 stays on the last 0.x release.