@nitrostack/widgets

Lightweight widget utilities for building interactive UI components in NitroStack MCP servers.

Installation

npm install @nitrostack/widgets

Features

• OpenAI ChatGPT Compatible - Works with OpenAI's widget format
• React Hooks - Easy-to-use hooks for widget state management
• Theme Support - Automatic dark/light mode detection
• Type Safe - Full TypeScript support

Quick Start

import { useWidgetSDK, useTheme, WidgetLayout } from '@nitrostack/widgets';

export default function MyWidget() {
  const sdk = useWidgetSDK();
  const { isDark } = useTheme();
  
  // Access tool output data
  const data = sdk.getOutput();
  
  return (
    <WidgetLayout>
      <div style={{ background: isDark ? '#1a1a1a' : '#ffffff' }}>
        <h1>Hello from Widget!</h1>
        <pre>{JSON.stringify(data, null, 2)}</pre>
      </div>
    </WidgetLayout>
  );
}

Hooks

useWidgetSDK()

Main SDK hook providing access to all widget functionality:

const sdk = useWidgetSDK();

// Get tool output data
const data = sdk.getOutput();

// Call another tool
const result = await sdk.callTool('tool_name', { param: 'value' });

// Update widget state
sdk.setState({ count: 1 });
const state = sdk.getState();

// Theme
const isDark = sdk.isDarkMode();

// Display mode
const mode = sdk.getDisplayMode(); // 'split' | 'fullscreen'

useTheme()

Access current theme:

const { isDark, theme } = useTheme();

useWidgetState(initialState)

Persistent widget state:

const [state, setState] = useWidgetState({ count: 0 });

useMaxHeight()

Get maximum available height for the widget:

const maxHeight = useMaxHeight(); // e.g., '600px'

useDisplayMode()

Get current display mode:

const displayMode = useDisplayMode(); // 'split' | 'fullscreen'

Components

WidgetLayout

Wrapper component that handles theme and polyfills:

import { WidgetLayout } from '@nitrostack/widgets';

export default function Page() {
  return (
    <WidgetLayout>
      <YourWidgetContent />
    </WidgetLayout>
  );
}

Utilities

import {
  prefersReducedMotion,
  isPrimarilyTouchDevice,
  isHoverAvailable,
  prefersDarkColorScheme,
} from '@nitrostack/widgets';

// Check user preferences
if (prefersReducedMotion()) {
  // Disable animations
}

License

Apache-2.0