1# Widget State
2 
3Widgets manage their own UI state (selections, filters, tabs, pagination). Never create tools to manage widget state.
4 
5**Key principle:** UI state lives in the widget. Server state lives in tools.
6 
7---
8 
9## Widget State vs Tool State
10 
11### Widget State (UI State)
12**Managed by widget with `useState` or `setState`:**
13- Current selected item
14- Active tab
15- Filter settings
16- Sort order
17- Pagination page
18- Expanded/collapsed sections
19- Form input values (before submission)
20 
21### Tool State (Server State)
22**Managed by server, returned in tool response:**
23- List of items
24- User data
25- API results
26- Computation results
27- Database queries
28 
29---
30 
31## Using React useState
32 
33Standard React state management works in widgets:
34 
35```tsx
36import { useState } from "react";
37import { McpUseProvider, useWidget, type WidgetMetadata } from "mcp-use/react";
38import { z } from "zod";
39 
40export const widgetMetadata: WidgetMetadata = {
41  description: "Product list with filtering",
42  props: z.object({
43    products: z.array(z.object({
44      id: z.string(),
45      name: z.string(),
46      category: z.string(),
47      price: z.number()
48    }))
49  }),
50  exposeAsTool: false
51};
52 
53export default function ProductList() {
54  const { props, isPending } = useWidget();
55  const [selectedCategory, setSelectedCategory] = useState<string>("all");
56  const [sortBy, setSortBy] = useState<"name" | "price">("name");
57 
58  if (isPending) {
59    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
60  }
61 
62  // Filter and sort based on state
63  const filtered = selectedCategory === "all"
64    ? props.products
65    : props.products.filter(p => p.category === selectedCategory);
66 
67  const sorted = [...filtered].sort((a, b) => {
68    if (sortBy === "name") return a.name.localeCompare(b.name);
69    return a.price - b.price;
70  });
71 
72  const categories = ["all", ...new Set(props.products.map(p => p.category))];
73 
74  return (
75    <McpUseProvider autoSize>
76      <div style={{ padding: 20 }}>
77        {/* Category filter */}
78        <div style={{ marginBottom: 16 }}>
79          {categories.map(cat => (
80            <button
81              key={cat}
82              onClick={() => setSelectedCategory(cat)}
83              style={{
84                padding: "8px 16px",
85                margin: "0 4px",
86                backgroundColor: selectedCategory === cat ? "#007bff" : "#f0f0f0",
87                color: selectedCategory === cat ? "white" : "black",
88                border: "none",
89                borderRadius: 4,
90                cursor: "pointer"
91              }}
92            >
93              {cat}
94            </button>
95          ))}
96        </div>
97 
98        {/* Sort controls */}
99        <div style={{ marginBottom: 16 }}>
100          <label>
101            Sort by:
102            <select value={sortBy} onChange={(e) => setSortBy(e.target.value as any)} style={{ marginLeft: 8 }}>
103              <option value="name">Name</option>
104              <option value="price">Price</option>
105            </select>
106          </label>
107        </div>
108 
109        {/* Product list */}
110        <div>
111          {sorted.map(product => (
112            <div key={product.id} style={{ padding: 12, border: "1px solid #ddd", marginBottom: 8 }}>
113              <h3>{product.name}</h3>
114              <p>Category: {product.category} | ${product.price}</p>
115            </div>
116          ))}
117        </div>
118      </div>
119    </McpUseProvider>
120  );
121}
122```
123 
124**Pattern:**
125- Tool provides data (products)
126- Widget manages UI state (selectedCategory, sortBy)
127- Widget renders filtered/sorted view
128- No additional tool calls needed
129 
130---
131 
132## Using setState from useWidget
133 
134The `setState` method from `useWidget()` is an alternative to React's `useState` with automatic state persistence across widget interactions. See [basics.md](basics.md#usewidget-hook) for full `useWidget()` API reference.
135 
136**When to use `setState` vs `useState`:**
137- Use `useState` for simple, ephemeral UI state (resets on widget unmount)
138- Use `setState` from `useWidget` for state that persists across interactions
139 
140---
141 
142## Selection State
143 
144Track which item(s) are selected:
145 
146```tsx
147import { useState } from "react";
148 
149export default function ItemSelector() {
150  const { props, isPending } = useWidget();
151  const [selectedId, setSelectedId] = useState<string | null>(null);
152 
153  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
154 
155  return (
156    <McpUseProvider autoSize>
157      <div>
158        {props.items.map(item => (
159          <div
160            key={item.id}
161            onClick={() => setSelectedId(item.id)}
162            style={{
163              padding: 12,
164              border: `2px solid ${selectedId === item.id ? "#007bff" : "#ddd"}`,
165              marginBottom: 8,
166              cursor: "pointer"
167            }}
168          >
169            {item.name}
170          </div>
171        ))}
172      </div>
173    </McpUseProvider>
174  );
175}
176```
177 
178### Multi-Select
179 
180```tsx
181const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
182 
183const toggleSelection = (id: string) => {
184  const newSelection = new Set(selectedIds);
185  if (newSelection.has(id)) {
186    newSelection.delete(id);
187  } else {
188    newSelection.add(id);
189  }
190  setSelectedIds(newSelection);
191};
192 
193return (
194  <McpUseProvider autoSize>
195    <div>
196      {props.items.map(item => (
197        <div
198          key={item.id}
199          onClick={() => toggleSelection(item.id)}
200          style={{
201            padding: 12,
202            backgroundColor: selectedIds.has(item.id) ? "#e3f2fd" : "white",
203            border: "1px solid #ddd"
204          }}
205        >
206          <input
207            type="checkbox"
208            checked={selectedIds.has(item.id)}
209            readOnly
210          />
211          {item.name}
212        </div>
213      ))}
214    </div>
215  </McpUseProvider>
216);
217```
218 
219---
220 
221## Tab State
222 
223Manage tabs without additional tool calls:
224 
225```tsx
226const [activeTab, setActiveTab] = useState<"overview" | "details" | "history">("overview");
227 
228return (
229  <McpUseProvider autoSize>
230    <div>
231      {/* Tab buttons */}
232      <div style={{ borderBottom: "1px solid #ddd", marginBottom: 16 }}>
233        {["overview", "details", "history"].map(tab => (
234          <button
235            key={tab}
236            onClick={() => setActiveTab(tab as any)}
237            style={{
238              padding: "8px 16px",
239              border: "none",
240              borderBottom: activeTab === tab ? "2px solid #007bff" : "none",
241              background: "none",
242              cursor: "pointer"
243            }}
244          >
245            {tab.charAt(0).toUpperCase() + tab.slice(1)}
246          </button>
247        ))}
248      </div>
249 
250      {/* Tab content */}
251      {activeTab === "overview" && <div>{/* Overview content */}</div>}
252      {activeTab === "details" && <div>{/* Details content */}</div>}
253      {activeTab === "history" && <div>{/* History content */}</div>}
254    </div>
255  </McpUseProvider>
256);
257```
258 
259---
260 
261## Pagination State
262 
263Paginate large lists client-side:
264 
265```tsx
266const [currentPage, setCurrentPage] = useState(1);
267const itemsPerPage = 10;
268 
269const totalPages = Math.ceil(props.items.length / itemsPerPage);
270const startIndex = (currentPage - 1) * itemsPerPage;
271const currentItems = props.items.slice(startIndex, startIndex + itemsPerPage);
272 
273return (
274  <McpUseProvider autoSize>
275    <div>
276      {/* Items */}
277      <div>
278        {currentItems.map(item => (
279          <div key={item.id}>{item.name}</div>
280        ))}
281      </div>
282 
283      {/* Pagination controls */}
284      <div style={{ marginTop: 16, display: "flex", gap: 8 }}>
285        <button
286          onClick={() => setCurrentPage(p => Math.max(1, p - 1))}
287          disabled={currentPage === 1}
288        >
289          Previous
290        </button>
291 
292        <span>
293          Page {currentPage} of {totalPages}
294        </span>
295 
296        <button
297          onClick={() => setCurrentPage(p => Math.min(totalPages, p + 1))}
298          disabled={currentPage === totalPages}
299        >
300          Next
301        </button>
302      </div>
303    </div>
304  </McpUseProvider>
305);
306```
307 
308---
309 
310## Filter State
311 
312Complex filtering:
313 
314```tsx
315interface Filters {
316  search: string;
317  category: string;
318  priceMin: number;
319  priceMax: number;
320}
321 
322const [filters, setFilters] = useState<Filters>({
323  search: "",
324  category: "all",
325  priceMin: 0,
326  priceMax: 1000
327});
328 
329const filteredItems = props.items.filter(item => {
330  if (filters.search && !item.name.toLowerCase().includes(filters.search.toLowerCase())) {
331    return false;
332  }
333  if (filters.category !== "all" && item.category !== filters.category) {
334    return false;
335  }
336  if (item.price < filters.priceMin || item.price > filters.priceMax) {
337    return false;
338  }
339  return true;
340});
341 
342return (
343  <McpUseProvider autoSize>
344    <div>
345      {/* Filter controls */}
346      <div style={{ marginBottom: 16 }}>
347        <input
348          type="text"
349          placeholder="Search..."
350          value={filters.search}
351          onChange={e => setFilters({ ...filters, search: e.target.value })}
352          style={{ padding: 8, marginRight: 8 }}
353        />
354 
355        <select
356          value={filters.category}
357          onChange={e => setFilters({ ...filters, category: e.target.value })}
358          style={{ padding: 8, marginRight: 8 }}
359        >
360          <option value="all">All Categories</option>
361          {/* ... category options */}
362        </select>
363 
364        <input
365          type="number"
366          value={filters.priceMin}
367          onChange={e => setFilters({ ...filters, priceMin: Number(e.target.value) })}
368          placeholder="Min price"
369          style={{ width: 80, padding: 8, marginRight: 8 }}
370        />
371 
372        <input
373          type="number"
374          value={filters.priceMax}
375          onChange={e => setFilters({ ...filters, priceMax: Number(e.target.value) })}
376          placeholder="Max price"
377          style={{ width: 80, padding: 8 }}
378        />
379      </div>
380 
381      {/* Filtered items */}
382      <div>
383        {filteredItems.map(item => (
384          <div key={item.id}>{item.name} - ${item.price}</div>
385        ))}
386      </div>
387    </div>
388  </McpUseProvider>
389);
390```
391 
392---
393 
394## Expand/Collapse State
395 
396Accordion or expandable sections:
397 
398```tsx
399const [expandedIds, setExpandedIds] = useState<Set<string>>(new Set());
400 
401const toggleExpand = (id: string) => {
402  const newExpanded = new Set(expandedIds);
403  if (newExpanded.has(id)) {
404    newExpanded.delete(id);
405  } else {
406    newExpanded.add(id);
407  }
408  setExpandedIds(newExpanded);
409};
410 
411return (
412  <McpUseProvider autoSize>
413    <div>
414      {props.items.map(item => (
415        <div key={item.id} style={{ marginBottom: 8 }}>
416          <div
417            onClick={() => toggleExpand(item.id)}
418            style={{
419              padding: 12,
420              backgroundColor: "#f5f5f5",
421              cursor: "pointer",
422              display: "flex",
423              justifyContent: "space-between"
424            }}
425          >
426            <span>{item.title}</span>
427            <span>{expandedIds.has(item.id) ? "▼" : "▶"}</span>
428          </div>
429 
430          {expandedIds.has(item.id) && (
431            <div style={{ padding: 12, border: "1px solid #ddd" }}>
432              {item.details}
433            </div>
434          )}
435        </div>
436      ))}
437    </div>
438  </McpUseProvider>
439);
440```
441 
442---
443 
444## Form State
445 
446Track form inputs before submission:
447 
448```tsx
449const [formData, setFormData] = useState({
450  name: "",
451  email: "",
452  message: ""
453});
454 
455const handleChange = (field: string, value: string) => {
456  setFormData(prev => ({ ...prev, [field]: value }));
457};
458 
459return (
460  <McpUseProvider autoSize>
461    <form onSubmit={(e) => {
462      e.preventDefault();
463      // Handle submission (see interactivity.md)
464    }}>
465      <input
466        type="text"
467        value={formData.name}
468        onChange={(e) => handleChange("name", e.target.value)}
469        placeholder="Name"
470      />
471 
472      <input
473        type="email"
474        value={formData.email}
475        onChange={(e) => handleChange("email", e.target.value)}
476        placeholder="Email"
477      />
478 
479      <textarea
480        value={formData.message}
481        onChange={(e) => handleChange("message", e.target.value)}
482        placeholder="Message"
483      />
484 
485      <button type="submit">Send</button>
486    </form>
487  </McpUseProvider>
488);
489```
490 
491---
492 
493## State Initialization
494 
495Initialize state based on props:
496 
497```tsx
498const [selectedCategory, setSelectedCategory] = useState<string>("");
499 
500// Initialize when props load
501useEffect(() => {
502  if (props.categories && props.categories.length > 0 && !selectedCategory) {
503    setSelectedCategory(props.categories[0]);
504  }
505}, [props.categories, selectedCategory]);
506```
507 
508**Note:** Lazy initialization like `useState(() => props.categories?.[0] || "all")` won't work here — on the first render `isPending` is `true` and `props` is `{}`, so the initializer always resolves to `"all"`. The `useEffect` pattern above is the correct approach for props that arrive asynchronously.
509 
510---
511 
512## Common Patterns
513 
514### Search + Filter + Sort
515```tsx
516const [search, setSearch] = useState("");
517const [category, setCategory] = useState("all");
518const [sortBy, setSortBy] = useState("name");
519 
520let filtered = props.items;
521 
522// Apply search
523if (search) {
524  filtered = filtered.filter(item =>
525    item.name.toLowerCase().includes(search.toLowerCase())
526  );
527}
528 
529// Apply category filter
530if (category !== "all") {
531  filtered = filtered.filter(item => item.category === category);
532}
533 
534// Apply sort
535filtered.sort((a, b) => {
536  if (sortBy === "name") return a.name.localeCompare(b.name);
537  if (sortBy === "price") return a.price - b.price;
538  return 0;
539});
540```
541 
542### Master-Detail View
543```tsx
544const [selectedId, setSelectedId] = useState<string | null>(null);
545 
546const selectedItem = selectedId
547  ? props.items.find(item => item.id === selectedId)
548  : null;
549 
550return (
551  <div style={{ display: "flex", gap: 16 }}>
552    {/* Master list */}
553    <div style={{ flex: 1 }}>
554      {props.items.map(item => (
555        <div
556          key={item.id}
557          onClick={() => setSelectedId(item.id)}
558          style={{
559            padding: 12,
560            backgroundColor: selectedId === item.id ? "#e3f2fd" : "white"
561          }}
562        >
563          {item.name}
564        </div>
565      ))}
566    </div>
567 
568    {/* Detail panel */}
569    <div style={{ flex: 2 }}>
570      {selectedItem ? (
571        <div>
572          <h2>{selectedItem.name}</h2>
573          <p>{selectedItem.description}</p>
574        </div>
575      ) : (
576        <p>Select an item to view details</p>
577      )}
578    </div>
579  </div>
580);
581```
582 
583---
584 
585## Anti-Patterns
586 
587### ❌ Don't Create Tools for UI State
588```typescript
589// ❌ Bad - Tool for UI state
590server.tool(
591  { name: "set-filter", schema: z.object({ category: z.string() }) },
592  async ({ category }) => {
593    // This is wrong! Filters should be widget state
594  }
595);
596 
597// ✅ Good - Widget manages its own filters
598const [filter, setFilter] = useState("all");
599```
600 
601### ❌ Don't Call Tools for Filtering/Sorting
602```typescript
603// ❌ Bad - Using a tool call for client-side filtering
604const { callTool: filterItems } = useCallTool("filter-items");
605<button onClick={() => filterItems({ category: "electronics" })}>
606  Filter
607</button>
608 
609// ✅ Good - Filter in widget
610<button onClick={() => setCategory("electronics")}>
611  Filter
612</button>
613```
614 
615### ❌ Don't Store UI State in Props
616```typescript
617// ❌ Bad - Trying to mutate props
618props.selectedId = "123";  // Error! Props are read-only
619 
620// ✅ Good - Use state
621const [selectedId, setSelectedId] = useState<string | null>(null);
622```
623 
624---
625 
626## Best Practices
627 
6281. **Keep state local** - Don't lift state unless necessary
6292. **Initialize from props** - Use props as initial data, state for UI
6303. **Use descriptive names** - `selectedCategory` not `filter`
6314. **Reset state appropriately** - When props change, update dependent state
6325. **Avoid unnecessary re-renders** - Use `useMemo` for expensive computations
633 
634---
635 
636## Next Steps
637 
638- **Add interactivity** → [interactivity.md](interactivity.md)
639- **Style widgets** → [ui-guidelines.md](ui-guidelines.md)
640- **Advanced patterns** → [advanced.md](advanced.md)
641