useWidget()

import { useWidget } from "mcp-use/react";

import { useWidget } from "mcp-use/react";

interface MyWidgetProps {
  city: string;
  temperature: number;
}

const MyWidget: React.FC = () => {
  // Works identically in both MCP Apps and ChatGPT
  const { props, theme, callTool } = useWidget<MyWidgetProps>();

  return (
    <div data-theme={theme}>
      <h1>{props.city}</h1>
      <p>{props.temperature}°C</p>
    </div>
  );
};

useWidget<
  TProps, // Props type (from toolInput)
  TOutput, // Output type (from toolOutput/structuredContent)
  TMetadata, // Metadata type (from toolResponseMetadata)
  TState // State type (for widgetState)
>();

const { hostInfo, hostCapabilities } = useWidget();

// Identify the host
if (hostInfo) {
  console.log(`Running inside ${hostInfo.name} ${hostInfo.version}`);
  // e.g. "claude-desktop 1.2.0"
}

// Check for optional host features
if (hostCapabilities?.openLinks) {
  // Host supports opening external URLs via ui/open-link
}

import { useWidget } from "mcp-use/react";

interface ProductProps {
  productId: string;
  name: string;
  price: number;
}

interface ProductOutput {
  reviews: Array<{ rating: number; comment: string }>;
}

interface ProductState {
  favorites: string[];
}

const ProductWidget: React.FC = () => {
  const {
    // Props and state
    props,
    output,
    state,
    setState,

    // Layout & theme
    theme,
    displayMode,
    safeArea,

    // Actions
    callTool,
    sendFollowUpMessage,
    openExternal,
    requestDisplayMode,
    notifyIntrinsicHeight,

    // Availability
    isAvailable,
  } = useWidget<ProductProps, ProductOutput, {}, ProductState>();

  const handleAddToFavorites = async () => {
    const newFavorites = [...(state?.favorites || []), props.productId];
    await setState({ favorites: newFavorites });
  };

  const handleGetReviews = async () => {
    const result = await callTool("get-product-reviews", {
      productId: props.productId,
    });
    // Handle result
  };

  return (
    <div data-theme={theme}>
      <h1>{props.name}</h1>
      <p>${props.price}</p>
      <button onClick={handleAddToFavorites}>Add to Favorites</button>
      <button onClick={handleGetReviews}>Get Reviews</button>
    </div>
  );
};

const MyWidget: React.FC = () => {
  const { props, isPending } = useWidget<MyWidgetProps>();

  if (isPending) {
    return <LoadingSpinner />;
  }

  // Safe to access props now
  return (
    <div>
      {props.city} - {props.temperature}°C
    </div>
  );
};

const MyWidget: React.FC = () => {
  const { props, isPending } = useWidget<MyWidgetProps>();

  return (
    <div>
      {isPending ? (
        <LoadingSpinner />
      ) : (
        <div>
          {props.city} - {props.temperature}°C
        </div>
      )}
    </div>
  );
};

const CodePreviewWidget: React.FC = () => {
  const { props, isPending, isStreaming, partialToolInput } = useWidget<{ code: string; language: string }>();

  if (isPending && !partialToolInput) {
    return <LoadingSpinner />;
  }

  // Show live preview during streaming, then final props when complete
  const displayCode = isStreaming && partialToolInput?.code != null
    ? partialToolInput.code
    : props.code ?? "";
  const displayLang = (isStreaming ? partialToolInput?.language : props.language) ?? "text";

  return (
    <pre data-language={displayLang}>
      {displayCode || "Waiting for input..."}
    </pre>
  );
};

import { useWidgetProps } from "mcp-use/react";

const props = useWidgetProps<{ city: string; temperature: number }>();
// { city: "Paris", temperature: 22 }

import { useWidgetTheme } from "mcp-use/react";

const theme = useWidgetTheme(); // 'light' | 'dark'

import { useWidgetState } from "mcp-use/react";

const [favorites, setFavorites] = useWidgetState<string[]>([]);

// Update state
await setFavorites(["item1", "item2"]);

// Or use functional update
await setFavorites((prev) => [...prev, "newItem"]);

// ❌ Don't do this
const MyWidget: React.FC<MyProps> = ({ city, temperature }) => { ... }

// ✅ Do this
const MyWidget: React.FC = () => {
  const { props } = useWidget<MyProps>();
  const { city, temperature } = props;
  // ...
}

const { notifyIntrinsicHeight } = useWidget();

useEffect(() => {
  const height = containerRef.current?.scrollHeight || 0;
  notifyIntrinsicHeight(height);
}, [content]);

const { state, setState } = useWidget<{}, {}, {}, { favorites: string[] }>();

// Update state
await setState({ favorites: ["item1", "item2"] });

// Functional update
await setState((prev) => ({
  favorites: [...(prev?.favorites || []), "newItem"],
}));

const { callTool } = useWidget();

const handleSearch = async () => {
  const result = await callTool("search-products", {
    query: "laptop",
  });
  // Handle result
};

const { sendFollowUpMessage } = useWidget();

// String shorthand (most common)
const handleRequestInfo = async () => {
  await sendFollowUpMessage("Show me more details about this product");
};

// Full content array (MCP Apps — supports text, image, resource blocks)
const handleRichMessage = async () => {
  await sendFollowUpMessage([
    { type: "text", text: "Show me more details about this product" },
  ]);
};

const { requestDisplayMode } = useWidget();

const handleFullscreen = async () => {
  const result = await requestDisplayMode("fullscreen");
  // result.mode is the granted mode (may differ from requested)
};

const { callTool, isAvailable } = useWidget();

const handleAction = async () => {
  if (!isAvailable) {
    console.warn("Widget API not available");
    return;
  }

  try {
    await callTool("my-tool", {});
  } catch (error) {
    console.error("Tool call failed:", error);
  }
};