UI Kit

streamvi-ui contains React components for plugin interfaces in the StreamVi style. The current package and import name is @streamvi/streamvi-ui-kit. The library uses Material UI and supports light and dark themes.

Installation

Install the library from GitHub in a React application:

npm install git+https://github.com/StreamVi/streamvi-ui.git

Compatible React, MUI and Emotion versions are listed in peerDependencies in package.json. Modern npm installs missing peer dependencies automatically. If they already exist in your application, check compatibility before updating. Keep package-lock.json to pin the installation result. This command does not require an npm release.

First component

Wrap your interface in SvThemeProvider. A React application entry file can look like this:

import { SvButton, SvThemeProvider } from '@streamvi/streamvi-ui-kit';
import '@streamvi/streamvi-ui-kit/fonts.css';

export function App() {
  return (
    <SvThemeProvider defaultMode="light">
      <SvButton onClick={() => alert('Ready')}>Test button</SvButton>
    </SvThemeProvider>
  );
}

The fonts.css import is optional and loads Inter. Components receive styles through MUI and Emotion; the library does not use a separate style.css import. Your application controls the page background, layout and global styles. UI Kit does not add CssBaseline automatically.

Components

The main components are listed below. Full props and examples are in the UI Kit README.

Purpose	Components
Actions	SvButton, SvIconButton, SvMenu
Text and number input	SvField, SvNumberField, SvTagInput
Value selection	SvCheckbox, SvRadio, SvRadioGroup, SvSelect, SvSlider, SvSwitch
Labels and hints	SvChip, SvTooltip

Handlers differ: for example, SvField provides the value in event.target.value, while SvNumberField passes a number or null as the second onChange argument. Use the current version's types instead of copying props from old components.

Plugin theme

Inside the provider, useSvColorScheme() returns mode and setMode. Available modes are light, dark and system. mode may be missing on the first render. defaultMode sets the initial choice; a saved user preference may take precedence.

During widget messaging, Cabinet sends payload.theme. After validating the sender, apply it through setMode('light') or setMode('dark'). UI Kit does not listen for Cabinet messages itself. Embedded pages do not use this settings protocol.

Settings form

This component receives its theme and field value from its parent. Editing the field calls onTitleChange; submitting the form calls onSave. An empty title cannot be submitted.

import { useEffect } from 'react';
import {
  SvButton, SvField, SvThemeProvider, useSvColorScheme,
} from '@streamvi/streamvi-ui-kit';

type SettingsProps = {
  theme: 'light' | 'dark';
  title: string;
  onTitleChange: (title: string) => void;
  onSave: () => void;
};

export function WidgetSettings(props: SettingsProps) {
  return (
    <SvThemeProvider defaultMode={props.theme} storageManager={null}>
      <SettingsForm {...props} />
    </SvThemeProvider>
  );
}

function SettingsForm({ theme, title, onTitleChange, onSave }: SettingsProps) {
  const { setMode } = useSvColorScheme();
  useEffect(() => { setMode(theme); }, [theme, setMode]);
  const invalid = title.trim().length === 0;

  return (
    <form onSubmit={event => {
      event.preventDefault();
      if (!invalid) onSave();
    }}>
      <SvField
        label="Title"
        value={title}
        onChange={event => onTitleChange(event.target.value)}
        error={invalid}
        helperText={invalid ? 'Enter a title' : undefined}
      />
      <SvButton type="submit" disabled={invalid}>Save</SvButton>
    </form>
  );
}

Pass theme from a validated Cabinet message and title from the current settings. Keep the draft in the parent: onTitleChange updates it, and onSave sends the complete settings object using the widget protocol, preserving other fields. The init and sync messages only update form state and must not trigger an update response. UI Kit does not save settings itself.

storageManager={null} disables a saved theme preference in this example so that the Cabinet theme remains authoritative. Changes to theme are applied through setMode; defaultMode alone does not handle subsequent switches.

TypeScript

The package uses ESM. For an application with a bundler, configure moduleResolution: "bundler"; for Node.js, use matching module and moduleResolution: "NodeNext" settings.

If a build with exactOptionalPropertyTypes: true reports errors in MUI 9.5 declarations for Collapse or Fade, first check dependency compatibility. This is a known dependency typing issue, not a required UI Kit setting. A temporary workaround is skipLibCheck: true. It skips checking all library .d.ts files, so do not add it without encountering this issue.

Migrating from the old version

The viewer counter uses the previous @streamvi/streamvi-ui package pinned to another revision. It has a different component foundation, imports and handlers. Updating to @streamvi/streamvi-ui-kit requires migration, not just replacing a dependency. Keep the example's original versions to run it; use the current UI Kit for a new interface.