useWidgetProps

Access props passed to your widget from the ChatGPT host environment. This hook allows your widget to receive configuration data, user preferences, or any custom data the host application wants to share.

Usage

import { useWidgetProps } from '@chatgpt-apps/sdk';

function MyWidget() {
  const props = useWidgetProps<{
    theme: 'light' | 'dark';
    userId: string;
    apiKey: string;
  }>();

  return (
    <div className={props.theme}>
      <p>User ID: {props.userId}</p>
    </div>
  );
}

Parameters

This hook accepts an optional generic type parameter for TypeScript type inference:

Parameter	Type	Description
`T`	`generic`	Optional type parameter to define the shape of widget props

Return Type

Returns the widget props object with the type T (defaults to Record<string, unknown> if no generic is provided).

interface WidgetProps {
  [key: string]: unknown;
}

type ReturnType<T = WidgetProps> = T;

Example

Basic Usage

import { useWidgetProps } from '@chatgpt-apps/sdk';

function WeatherWidget() {
  const { location, units } = useWidgetProps<{
    location: string;
    units: 'celsius' | 'fahrenheit';
  }>();

  return (
    <div>
      <h2>Weather for {location}</h2>
      <p>Units: {units}</p>
    </div>
  );
}

With Default Values

import { useWidgetProps } from '@chatgpt-apps/sdk';

function ConfigurableWidget() {
  const props = useWidgetProps<{
    title?: string;
    showHeader?: boolean;
  }>();

  const title = props.title ?? 'Default Title';
  const showHeader = props.showHeader ?? true;

  return (
    <div>
      {showHeader && <h1>{title}</h1>}
      <p>Widget content</p>
    </div>
  );
}

Type-Safe Props

import { useWidgetProps } from '@chatgpt-apps/sdk';

interface MyWidgetProps {
  apiEndpoint: string;
  refreshInterval: number;
  features: {
    enableSearch: boolean;
    enableFilters: boolean;
  };
}

function AdvancedWidget() {
  const { apiEndpoint, refreshInterval, features } = useWidgetProps<MyWidgetProps>();

  return (
    <div>
      <p>API: {apiEndpoint}</p>
      <p>Refresh: {refreshInterval}ms</p>
      <p>Search: {features.enableSearch ? 'On' : 'Off'}</p>
    </div>
  );
}

Notes

Props are provided by the host application when embedding your widget
Always provide default values for optional props
Use TypeScript generics for type safety
Props are immutable; treat them as read-only

useWidgetProps

On this page