useDisplayMode

Get the current display mode of your widget. The display mode indicates how your widget is being rendered within the ChatGPT interface.

Usage

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

function MyWidget() {
  const displayMode = useDisplayMode();

  return (
    <div>
      <p>Current mode: {displayMode}</p>
      {displayMode === 'fullscreen' && <ExpandedView />}
      {displayMode === 'pip' && <CompactView />}
      {displayMode === 'inline' && <StandardView />}
    </div>
  );
}

Parameters

This hook accepts no parameters.

Return Type

Returns a DisplayMode string literal type.

type DisplayMode = 'pip' | 'inline' | 'fullscreen';

Mode	Description
`pip`	Picture-in-picture mode - widget appears as a small floating overlay
`inline`	Inline mode - widget is embedded directly in the conversation
`fullscreen`	Fullscreen mode - widget takes up the full available space

Example

Responsive Layout

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

function ResponsiveWidget() {
  const displayMode = useDisplayMode();

  const getLayoutClasses = () => {
    switch (displayMode) {
      case 'fullscreen':
        return 'grid grid-cols-3 gap-4 p-8';
      case 'inline':
        return 'grid grid-cols-2 gap-4 p-4';
      case 'pip':
        return 'flex flex-col p-2';
      default:
        return 'p-4';
    }
  };

  return (
    <div className={getLayoutClasses()}>
      <Card title="Item 1" />
      <Card title="Item 2" />
      <Card title="Item 3" />
    </div>
  );
}

Conditional Features

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

function FeatureWidget() {
  const displayMode = useDisplayMode();

  return (
    <div>
      <h1>My Widget</h1>
      
      {/* Only show detailed controls in fullscreen */}
      {displayMode === 'fullscreen' && (
        <AdvancedControls />
      )}

      {/* Show minimal UI in pip mode */}
      {displayMode === 'pip' ? (
        <MinimalStatus />
      ) : (
        <FullDashboard />
      )}
    </div>
  );
}

Mode Indicator

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

function ModeIndicator() {
  const displayMode = useDisplayMode();

  const modeConfig = {
    pip: { icon: '🔲', label: 'Floating' },
    inline: { icon: '⬜', label: 'Embedded' },
    fullscreen: { icon: '⬛', label: 'Fullscreen' },
  };

  const { icon, label } = modeConfig[displayMode];

  return (
    <div className="mode-badge">
      <span>{icon}</span>
      <span>{label}</span>
    </div>
  );
}

Notes

The display mode is controlled by the user or host application
Use useRequestDisplayMode to request a mode change
Your widget should adapt its UI to each display mode for the best user experience
The pip mode is ideal for persistent, non-intrusive widgets
The fullscreen mode is best for complex interactions and detailed views

useDisplayMode

On this page