Widget UI Guidelines

Build widgets that adapt to themes, look professional, and provide great user experience.

Key topics: Theme support, light/dark mode, responsive layouts, accessibility, CSS best practices

Theme Support with useWidgetTheme()

Widgets should adapt to the user's theme (light/dark mode):

import { McpUseProvider, useWidget, useWidgetTheme, type WidgetMetadata } from "mcp-use/react";
import { z } from "zod";

export const widgetMetadata: WidgetMetadata = {
  description: "Theme-aware widget",
  props: z.object({
    message: z.string()
  }),
  exposeAsTool: false
};

export default function ThemedWidget() {
  const { props, isPending } = useWidget();
  const theme = useWidgetTheme();

  if (isPending) {
    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
  }

  return (
    <McpUseProvider autoSize>
      <div style={{
        padding: 20,
        backgroundColor: theme === "dark" ? "#1e1e1e" : "#ffffff",
        color: theme === "dark" ? "#ffffff" : "#000000"
      }}>
        <p>{props.message}</p>
      </div>
    </McpUseProvider>
  );
}

useWidgetTheme() returns: "light" or "dark"

Theme-Aware Colors

Define color palettes for both themes:

const theme = useWidgetTheme();

const colors = {
  background: theme === "dark" ? "#1e1e1e" : "#ffffff",
  text: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
  border: theme === "dark" ? "#404040" : "#e0e0e0",
  primary: theme === "dark" ? "#4a9eff" : "#0066cc",
  secondary: theme === "dark" ? "#6c757d" : "#6c757d",
  hover: theme === "dark" ? "#2a2a2a" : "#f5f5f5",
  error: theme === "dark" ? "#ff6b6b" : "#dc3545",
  success: theme === "dark" ? "#51cf66" : "#28a745"
};

return (
  <McpUseProvider autoSize>
    <div style={{
      backgroundColor: colors.background,
      color: colors.text,
      border: `1px solid ${colors.border}`
    }}>
      {/* Your content */}
    </div>
  </McpUseProvider>
);

Or extract to a hook:

function useColors() {
  const theme = useWidgetTheme();

  return {
    background: theme === "dark" ? "#1e1e1e" : "#ffffff",
    text: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
    border: theme === "dark" ? "#404040" : "#e0e0e0",
    primary: theme === "dark" ? "#4a9eff" : "#0066cc",
    hover: theme === "dark" ? "#2a2a2a" : "#f5f5f5",
    error: theme === "dark" ? "#ff6b6b" : "#dc3545"
  };
}

export default function ThemedWidget() {
  const colors = useColors();
  // ... rest of component
}

Responsive Layouts

Grid Layout

<div style={{
  display: "grid",
  gridTemplateColumns: "repeat(auto-fill, minmax(200px, 1fr))",
  gap: 16,
  padding: 20
}}>
  {props.items.map(item => (
    <div key={item.id} style={{
      padding: 12,
      border: `1px solid ${colors.border}`,
      borderRadius: 8
    }}>
      {item.name}
    </div>
  ))}
</div>

Flexbox Layout

<div style={{
  display: "flex",
  gap: 16,
  padding: 20,
  flexWrap: "wrap"
}}>
  {props.items.map(item => (
    <div key={item.id} style={{
      flex: "1 1 200px",
      padding: 12,
      border: `1px solid ${colors.border}`
    }}>
      {item.name}
    </div>
  ))}
</div>

Two-Column Layout

<div style={{
  display: "flex",
  gap: 16,
  padding: 20
}}>
  {/* Sidebar */}
  <div style={{ flex: "0 0 250px" }}>
    {/* Navigation or filters */}
  </div>

  {/* Main content */}
  <div style={{ flex: 1 }}>
    {/* Primary content */}
  </div>
</div>

Button Styles

Theme-aware buttons:

const theme = useWidgetTheme();

const buttonStyle: React.CSSProperties = {
  padding: "8px 16px",
  border: "none",
  borderRadius: 4,
  cursor: "pointer",
  fontSize: 14,
  fontWeight: 500,
  backgroundColor: theme === "dark" ? "#4a9eff" : "#0066cc",
  color: "#ffffff"
};

const secondaryButtonStyle: React.CSSProperties = {
  ...buttonStyle,
  backgroundColor: "transparent",
  border: `1px solid ${theme === "dark" ? "#404040" : "#e0e0e0"}`,
  color: theme === "dark" ? "#e0e0e0" : "#1a1a1a"
};

return (
  <McpUseProvider autoSize>
    <div>
      <button style={buttonStyle}>Primary Action</button>
      <button style={secondaryButtonStyle}>Secondary</button>
    </div>
  </McpUseProvider>
);

Button States

const [hovered, setHovered] = useState(false);

<button
  style={{
    padding: "8px 16px",
    backgroundColor: hovered ? (theme === "dark" ? "#5aa8ff" : "#0052a3") : (theme === "dark" ? "#4a9eff" : "#0066cc"),
    color: "#ffffff",
    border: "none",
    borderRadius: 4,
    cursor: "pointer",
    transition: "background-color 0.2s"
  }}
  onMouseEnter={() => setHovered(true)}
  onMouseLeave={() => setHovered(false)}
>
  Hover Me
</button>

Card Components

const theme = useWidgetTheme();

const cardStyle: React.CSSProperties = {
  padding: 16,
  border: `1px solid ${theme === "dark" ? "#404040" : "#e0e0e0"}`,
  borderRadius: 8,
  backgroundColor: theme === "dark" ? "#1e1e1e" : "#ffffff",
  color: theme === "dark" ? "#e0e0e0" : "#1a1a1a"
};

return (
  <McpUseProvider autoSize>
    <div style={{ padding: 20 }}>
      {props.items.map(item => (
        <div key={item.id} style={{
          ...cardStyle,
          marginBottom: 12
        }}>
          <h3 style={{ margin: "0 0 8px 0" }}>{item.title}</h3>
          <p style={{ margin: 0, color: theme === "dark" ? "#b0b0b0" : "#666" }}>
            {item.description}
          </p>
        </div>
      ))}
    </div>
  </McpUseProvider>
);

Typography

const theme = useWidgetTheme();

<div style={{ padding: 20 }}>
  {/* Heading */}
  <h1 style={{
    fontSize: 24,
    fontWeight: 600,
    margin: "0 0 16px 0",
    color: theme === "dark" ? "#ffffff" : "#1a1a1a"
  }}>
    Title
  </h1>

  {/* Subheading */}
  <h2 style={{
    fontSize: 18,
    fontWeight: 500,
    margin: "0 0 12px 0",
    color: theme === "dark" ? "#e0e0e0" : "#333"
  }}>
    Subtitle
  </h2>

  {/* Body text */}
  <p style={{
    fontSize: 14,
    lineHeight: 1.5,
    margin: "0 0 12px 0",
    color: theme === "dark" ? "#b0b0b0" : "#666"
  }}>
    Body content here
  </p>

  {/* Small text */}
  <span style={{
    fontSize: 12,
    color: theme === "dark" ? "#808080" : "#999"
  }}>
    Small text or metadata
  </span>
</div>

Form Inputs

const theme = useWidgetTheme();

const inputStyle: React.CSSProperties = {
  padding: 8,
  fontSize: 14,
  border: `1px solid ${theme === "dark" ? "#404040" : "#d0d0d0"}`,
  borderRadius: 4,
  backgroundColor: theme === "dark" ? "#2a2a2a" : "#ffffff",
  color: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
  outline: "none"
};

<form style={{ padding: 20 }}>
  <label style={{
    display: "block",
    marginBottom: 4,
    fontSize: 14,
    fontWeight: 500,
    color: theme === "dark" ? "#e0e0e0" : "#333"
  }}>
    Name
  </label>
  <input
    type="text"
    style={inputStyle}
    placeholder="Enter name..."
  />

  <label style={{ display: "block", marginTop: 12, marginBottom: 4 }}>
    Description
  </label>
  <textarea
    style={{
      ...inputStyle,
      width: "100%",
      minHeight: 80,
      resize: "vertical"
    }}
    placeholder="Enter description..."
  />
</form>

Lists

const theme = useWidgetTheme();

<ul style={{
  listStyle: "none",
  padding: 0,
  margin: 0
}}>
  {props.items.map(item => (
    <li
      key={item.id}
      style={{
        padding: 12,
        borderBottom: `1px solid ${theme === "dark" ? "#2a2a2a" : "#f0f0f0"}`,
        cursor: "pointer",
        transition: "background-color 0.15s"
      }}
      onMouseEnter={(e) => {
        e.currentTarget.style.backgroundColor = theme === "dark" ? "#2a2a2a" : "#f5f5f5";
      }}
      onMouseLeave={(e) => {
        e.currentTarget.style.backgroundColor = "transparent";
      }}
    >
      {item.name}
    </li>
  ))}
</ul>

Badges and Tags

const theme = useWidgetTheme();

const badgeStyle: React.CSSProperties = {
  display: "inline-block",
  padding: "4px 8px",
  fontSize: 12,
  fontWeight: 500,
  borderRadius: 12,
  backgroundColor: theme === "dark" ? "#2a4a6a" : "#e3f2fd",
  color: theme === "dark" ? "#4a9eff" : "#0066cc"
};

<div>
  <span style={badgeStyle}>New</span>
  <span style={{ ...badgeStyle, marginLeft: 8 }}>Featured</span>
</div>

Loading States

const theme = useWidgetTheme();

if (isPending) {
  return (
    <McpUseProvider autoSize>
      <div style={{
        padding: 40,
        textAlign: "center",
        color: theme === "dark" ? "#808080" : "#999"
      }}>
        <div style={{
          width: 40,
          height: 40,
          border: `4px solid ${theme === "dark" ? "#404040" : "#e0e0e0"}`,
          borderTop: `4px solid ${theme === "dark" ? "#4a9eff" : "#0066cc"}`,
          borderRadius: "50%",
          margin: "0 auto 16px",
          animation: "spin 1s linear infinite"
        }} />
        <p>Loading...</p>
      </div>
    </McpUseProvider>
  );
}

Add spin animation:

<style>
  {`
    @keyframes spin {
      0% { transform: rotate(0deg); }
      100% { transform: rotate(360deg); }
    }
  `}
</style>

Empty States

const theme = useWidgetTheme();

{props.items.length === 0 && (
  <div style={{
    padding: 40,
    textAlign: "center",
    color: theme === "dark" ? "#808080" : "#999"
  }}>
    <div style={{
      fontSize: 48,
      marginBottom: 16,
      opacity: 0.5
    }}>
      📭
    </div>
    <h3 style={{
      fontSize: 18,
      fontWeight: 500,
      margin: "0 0 8px 0",
      color: theme === "dark" ? "#b0b0b0" : "#666"
    }}>
      No items yet
    </h3>
    <p style={{
      fontSize: 14,
      margin: 0,
      color: theme === "dark" ? "#808080" : "#999"
    }}>
      Get started by creating your first item
    </p>
  </div>
)}

Error States

const theme = useWidgetTheme();

{error && (
  <div style={{
    padding: 12,
    marginBottom: 16,
    backgroundColor: theme === "dark" ? "#3d1f1f" : "#ffebee",
    color: theme === "dark" ? "#ff6b6b" : "#c62828",
    border: `1px solid ${theme === "dark" ? "#6b2a2a" : "#ffcdd2"}`,
    borderRadius: 4
  }}>
    <strong>Error:</strong> {error}
  </div>
)}

Icons

Use Unicode emojis or SVG icons:

// Emojis
<span style={{ fontSize: 24, marginRight: 8 }}>⚙️</span>
<span style={{ fontSize: 20 }}>✓</span>
<span>❌</span>

// SVG icon
<svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor">
  <path d="M10 15l-5.878 3.09 1.123-6.545L.489 6.91l6.572-.955L10 0l2.939 5.955 6.572.955-4.756 4.635 1.123 6.545z"/>
</svg>

Spacing Guidelines

// Consistent spacing units
const spacing = {
  xs: 4,
  sm: 8,
  md: 12,
  lg: 16,
  xl: 20,
  xxl: 24
};

<div style={{
  padding: spacing.lg,
  gap: spacing.md
}}>
  {/* Content */}
</div>

Accessibility

Labels for Inputs

<label htmlFor="email-input">Email</label>
<input id="email-input" type="email" />

Alt Text for Images

<img src={item.image} alt={item.name} />

Button Labels

<button aria-label="Delete item">🗑️</button>

Keyboard Navigation

<div
  tabIndex={0}
  onKeyDown={(e) => {
    if (e.key === "Enter" || e.key === " ") {
      handleClick();
    }
  }}
>
  Clickable item
</div>

Auto-Size Best Practices

<McpUseProvider autoSize> automatically resizes iframe to content.

Tips:

• Use autoSize for dynamic content
• Avoid fixed heights unless necessary
• Widget resizes when content changes
• Test with varying content sizes

// ✅ Good - autoSize handles height
<McpUseProvider autoSize>
  <div style={{ padding: 20 }}>
    {/* Dynamic content */}
  </div>
</McpUseProvider>

// ❌ Bad - Fixed height defeats autoSize
<McpUseProvider autoSize>
  <div style={{ height: 400, overflow: "auto" }}>
    {/* Content */}
  </div>
</McpUseProvider>

Complete Themed Widget

import { useState } from "react";
import { McpUseProvider, useWidget, useWidgetTheme, type WidgetMetadata } from "mcp-use/react";
import { z } from "zod";

function useColors() {
  const theme = useWidgetTheme();

  return {
    background: theme === "dark" ? "#1e1e1e" : "#ffffff",
    text: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
    textSecondary: theme === "dark" ? "#b0b0b0" : "#666",
    border: theme === "dark" ? "#404040" : "#e0e0e0",
    hover: theme === "dark" ? "#2a2a2a" : "#f5f5f5",
    primary: theme === "dark" ? "#4a9eff" : "#0066cc"
  };
}

export const widgetMetadata: WidgetMetadata = {
  description: "Fully themed product list",
  props: z.object({
    products: z.array(z.object({
      id: z.string(),
      name: z.string(),
      price: z.number(),
      category: z.string()
    }))
  }),
  exposeAsTool: false
};

export default function ThemedProductList() {
  const { props, isPending } = useWidget();
  const colors = useColors();
  const [selectedCategory, setSelectedCategory] = useState("all");

  if (isPending) {
    return (
      <McpUseProvider autoSize>
        <div style={{
          padding: 40,
          textAlign: "center",
          color: colors.textSecondary
        }}>
          Loading...
        </div>
      </McpUseProvider>
    );
  }

  const categories = ["all", ...new Set(props.products.map(p => p.category))];
  const filtered = selectedCategory === "all"
    ? props.products
    : props.products.filter(p => p.category === selectedCategory);

  return (
    <McpUseProvider autoSize>
      <div style={{
        padding: 20,
        backgroundColor: colors.background,
        color: colors.text
      }}>
        <h2 style={{ margin: "0 0 16px 0" }}>Products</h2>

        {/* Category filters */}
        <div style={{ marginBottom: 16, display: "flex", gap: 8 }}>
          {categories.map(cat => (
            <button
              key={cat}
              onClick={() => setSelectedCategory(cat)}
              style={{
                padding: "8px 16px",
                borderRadius: 4,
                cursor: "pointer",
                backgroundColor: selectedCategory === cat ? colors.primary : "transparent",
                color: selectedCategory === cat ? "#fff" : colors.text,
                border: `1px solid ${selectedCategory === cat ? colors.primary : colors.border}`
              }}
            >
              {cat}
            </button>
          ))}
        </div>

        {/* Product grid */}
        <div style={{
          display: "grid",
          gridTemplateColumns: "repeat(auto-fill, minmax(200px, 1fr))",
          gap: 12
        }}>
          {filtered.map(product => (
            <div
              key={product.id}
              style={{
                padding: 12,
                border: `1px solid ${colors.border}`,
                borderRadius: 8,
                backgroundColor: colors.background
              }}
            >
              <h3 style={{ margin: "0 0 4px 0", fontSize: 16 }}>
                {product.name}
              </h3>
              <p style={{ margin: "0 0 8px 0", fontSize: 12, color: colors.textSecondary }}>
                {product.category}
              </p>
              <p style={{ margin: 0, fontSize: 18, fontWeight: "bold", color: colors.primary }}>
                ${product.price}
              </p>
            </div>
          ))}
        </div>

        {filtered.length === 0 && (
          <div style={{
            padding: 40,
            textAlign: "center",
            color: colors.textSecondary
          }}>
            No products in this category
          </div>
        )}
      </div>
    </McpUseProvider>
  );
}

Next Steps

• Advanced patterns → advanced.md
• See examples → ../patterns/common-patterns.md