@mediansh/widget

The Median support widget. A launcher in the corner of your site opens into a support panel. An AI agent answers first, your team picks up in the Median inbox, and replies stream back to the visitor. There is no connection or message list to manage.

The same panel as a modal, a contact form, and a feedback panel ship alongside it. Same key, same inbox.

Install

npm install @mediansh/widget

Import the stylesheet once, wherever your global CSS lives:

import "@mediansh/widget/styles.css";

React

import { MedianSupport } from "@mediansh/widget";

<MedianSupport apiKey="median_pk_..." />;

Mount it once, anywhere in your tree. The median_pk_ id is derived from your server's MEDIAN_KEY; the docs show the one line helper.

On an app with auth, serve medianIdentity from a route and pass that instead. The key comes down with the signed in user, so the conversation follows the person rather than the browser:

<MedianSupport identity="/api/median/identity" />;

The markdown renderer and the screenshot code load on demand, so do not wrap this in dynamic(). That only delays the launcher.

Without React

import { mountMedianSupport } from "@mediansh/widget";

const support = mountMedianSupport({ apiKey: "median_pk_..." });

Same widget, same options, on any page with a bundler. The instance returns update for new options and unmount to take it off the page. React installs alongside as a peer dependency; your app does not use it.

Control it from anywhere

import { medianSupport } from "@mediansh/widget";

medianSupport.open();
medianSupport.attach("Crash trace", error.stack);
medianSupport.reportError(error); // from your error screen
medianSupport.reset(); // on sign out

React components can use useMedianSupport() for the same control with a live isOpen.

Modal

The widget, opened in the middle of the screen over a scrim rather than out of the corner. The button stays; every prop and every control is the same.

import { MedianSupportModal } from "@mediansh/widget";

<MedianSupportModal apiKey="median_pk_..." />;

mountMedianSupportModal is the version for pages without React. Mount one of the two, not both.

Contact form

A form where you put it, for the page where a chat panel is the wrong shape. An email and a message are always asked; add the rest:

import { MedianContactForm } from "@mediansh/widget";

<MedianContactForm
  apiKey="median_pk_..."
  fields={[
    { name: "name", label: "Name", required: true },
    { name: "topic", type: "select", options: ["Billing", "A bug"] },
  ]}
/>;

Sending starts a conversation in your inbox, exactly as the widget does, and the reply goes to the email given. mountMedianContactForm({ target, ... }) renders it into an element of yours on a page without React.

Or keep your own form and only borrow the send:

const contact = useMedianContact({ apiKey: "median_pk_..." });

await contact.send({ email, message, fields: { Topic: topic } });

sendMedianContact(options, message) is the same call as a plain function.

Feedback

A second panel, for notes rather than questions. It wraps a trigger of your own and opens under it:

import { MedianFeedback } from "@mediansh/widget";

<MedianFeedback apiKey="median_pk_...">
  <button>Share feedback</button>
</MedianFeedback>;

One box and one button. A model reads the note and files it as a bug or a suggestion, or drops it as spam. Nobody picks a category or writes a title, and the page it was written on rides along.

mountMedianFeedback is the version for pages without React, and medianFeedback / useMedianFeedback() open it from anywhere else.

Theming

Every piece reads shadcn-style CSS variables from your page and falls back to a plain light theme without them. They inherit your font.

Docs

Props, identity, diagnostics, the modal, the contact form, feedback, and agent tools: docs.median.sh, or the source at github.com/mediansh/median.

Credits

Icons are from Solar by 480 Design, licensed under CC BY 4.0.