1# Advanced Widget Patterns
2 
3Advanced techniques for building complex, performant widgets.
4 
5**Topics:** Error boundaries, memoization, async data fetching, code splitting, complex state management
6 
7---
8 
9## Error Boundaries
10 
11Catch React errors and display fallback UI:
12 
13```tsx
14import { Component, ReactNode } from "react";
15import { McpUseProvider, useWidget } from "mcp-use/react";
16 
17interface ErrorBoundaryProps {
18  children: ReactNode;
19}
20 
21interface ErrorBoundaryState {
22  hasError: boolean;
23  error: Error | null;
24}
25 
26class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
27  constructor(props: ErrorBoundaryProps) {
28    super(props);
29    this.state = { hasError: false, error: null };
30  }
31 
32  static getDerivedStateFromError(error: Error) {
33    return { hasError: true, error };
34  }
35 
36  componentDidCatch(error: Error, errorInfo: any) {
37    console.error("Widget error:", error, errorInfo);
38  }
39 
40  render() {
41    if (this.state.hasError) {
42      return (
43        <div style={{ padding: 20, color: "#c62828" }}>
44          <h3>Something went wrong</h3>
45          <p>{this.state.error?.message}</p>
46          <button onClick={() => this.setState({ hasError: false, error: null })}>
47            Try Again
48          </button>
49        </div>
50      );
51    }
52 
53    return this.props.children;
54  }
55}
56 
57// Usage
58export default function SafeWidget() {
59  const { props, isPending } = useWidget();
60 
61  if (isPending) {
62    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
63  }
64 
65  return (
66    <McpUseProvider autoSize>
67      <ErrorBoundary>
68        <WidgetContent props={props} />
69      </ErrorBoundary>
70    </McpUseProvider>
71  );
72}
73```
74 
75---
76 
77## useMemo for Performance
78 
79Memoize expensive computations:
80 
81```tsx
82import { useMemo } from "react";
83import { McpUseProvider, useWidget } from "mcp-use/react";
84 
85export default function OptimizedWidget() {
86  const { props, isPending } = useWidget();
87 
88  // Expensive computation - only runs when props.items changes
89  // Guard against isPending where props.items is undefined
90  const sortedAndFiltered = useMemo(() => {
91    if (!props.items) return { items: [], total: 0, avgScore: 0 };
92 
93    let result = props.items;
94 
95    // Filter
96    result = result.filter(item => item.active);
97 
98    // Sort
99    result.sort((a, b) => b.score - a.score);
100 
101    // Compute stats
102    return {
103      items: result,
104      total: result.length,
105      avgScore: result.length > 0
106        ? result.reduce((sum, item) => sum + item.score, 0) / result.length
107        : 0
108    };
109  }, [props.items]);
110 
111  if (isPending) {
112    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
113  }
114 
115  return (
116    <McpUseProvider autoSize>
117      <div style={{ padding: 20 }}>
118        <p>Total: {sortedAndFiltered.total}</p>
119        <p>Average: {sortedAndFiltered.avgScore.toFixed(2)}</p>
120 
121        {sortedAndFiltered.items.map(item => (
122          <div key={item.id}>{item.name}</div>
123        ))}
124      </div>
125    </McpUseProvider>
126  );
127}
128```
129 
130---
131 
132## useCallback for Stable Functions
133 
134Prevent unnecessary re-renders:
135 
136```tsx
137import { useCallback, useState } from "react";
138import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
139 
140export default function CallbackWidget() {
141  const { props, isPending } = useWidget();
142  const { callToolAsync } = useCallTool("process-item");
143  const [loadingId, setLoadingId] = useState<string | null>(null);
144 
145  // Stable function reference
146  const handleAction = useCallback(async (id: string) => {
147    setLoadingId(id);
148    try {
149      await callToolAsync({ id });
150    } finally {
151      setLoadingId(null);
152    }
153  }, [callToolAsync]);
154 
155  if (isPending) {
156    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
157  }
158 
159  return (
160    <McpUseProvider autoSize>
161      <div>
162        {props.items.map(item => (
163          <ItemRow
164            key={item.id}
165            item={item}
166            onAction={handleAction}
167            loading={loadingId === item.id}
168          />
169        ))}
170      </div>
171    </McpUseProvider>
172  );
173}
174 
175// Child component won't re-render unnecessarily
176const ItemRow = React.memo(({ item, onAction, loading }: any) => (
177  <div>
178    <span>{item.name}</span>
179    <button onClick={() => onAction(item.id)} disabled={loading}>
180      {loading ? "Processing..." : "Process"}
181    </button>
182  </div>
183));
184```
185 
186---
187 
188## Async Data Fetching (Client-Side)
189 
190Fetch additional data from widget:
191 
192```tsx
193import { useState, useEffect } from "react";
194import { McpUseProvider, useWidget } from "mcp-use/react";
195 
196export default function AsyncWidget() {
197  const { props, isPending } = useWidget();
198  const [details, setDetails] = useState<Record<string, unknown> | null>(null);
199  const [loading, setLoading] = useState(false);
200 
201  useEffect(() => {
202    if (!isPending && props.itemId) {
203      setLoading(true);
204      fetch(`/api/items/${props.itemId}/details`)
205        .then(res => res.json())
206        .then(data => setDetails(data))
207        .catch(err => console.error("Failed to load details:", err))
208        .finally(() => setLoading(false));
209    }
210  }, [isPending, props.itemId]);
211 
212  if (isPending) {
213    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
214  }
215 
216  return (
217    <McpUseProvider autoSize>
218      <div style={{ padding: 20 }}>
219        <h2>{props.title}</h2>
220 
221        {loading && <p>Loading details...</p>}
222 
223        {details && (
224          <div>
225            <h3>Details</h3>
226            <pre>{JSON.stringify(details, null, 2)}</pre>
227          </div>
228        )}
229      </div>
230    </McpUseProvider>
231  );
232}
233```
234 
235**Prefer tool calls over direct API calls:**
236```tsx
237// ✅ Better - Use useCallTool
238const { callToolAsync } = useCallTool("get-item-details");
239 
240useEffect(() => {
241  if (!isPending && props.itemId) {
242    setLoading(true);
243    callToolAsync({ id: props.itemId })
244      .then(result => setDetails(result))
245      .finally(() => setLoading(false));
246  }
247}, [isPending, props.itemId, callToolAsync]);
248```
249 
250---
251 
252## Complex State Management
253 
254Use useReducer for complex state:
255 
256```tsx
257import { useReducer } from "react";
258import { McpUseProvider, useWidget } from "mcp-use/react";
259 
260type State = {
261  selectedIds: Set<string>;
262  filters: { category: string; search: string };
263  sortBy: string;
264  sortOrder: "asc" | "desc";
265};
266 
267type Action =
268  | { type: "TOGGLE_SELECT"; id: string }
269  | { type: "SET_FILTER"; key: string; value: string }
270  | { type: "SET_SORT"; by: string }
271  | { type: "TOGGLE_SORT_ORDER" }
272  | { type: "RESET" };
273 
274function reducer(state: State, action: Action): State {
275  switch (action.type) {
276    case "TOGGLE_SELECT":
277      const newSelection = new Set(state.selectedIds);
278      if (newSelection.has(action.id)) {
279        newSelection.delete(action.id);
280      } else {
281        newSelection.add(action.id);
282      }
283      return { ...state, selectedIds: newSelection };
284 
285    case "SET_FILTER":
286      return {
287        ...state,
288        filters: { ...state.filters, [action.key]: action.value }
289      };
290 
291    case "SET_SORT":
292      return { ...state, sortBy: action.by };
293 
294    case "TOGGLE_SORT_ORDER":
295      return {
296        ...state,
297        sortOrder: state.sortOrder === "asc" ? "desc" : "asc"
298      };
299 
300    case "RESET":
301      return {
302        selectedIds: new Set(),
303        filters: { category: "all", search: "" },
304        sortBy: "name",
305        sortOrder: "asc"
306      };
307 
308    default:
309      return state;
310  }
311}
312 
313export default function ComplexWidget() {
314  const { props, isPending } = useWidget();
315  const [state, dispatch] = useReducer(reducer, {
316    selectedIds: new Set(),
317    filters: { category: "all", search: "" },
318    sortBy: "name",
319    sortOrder: "asc"
320  });
321 
322  if (isPending) {
323    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
324  }
325 
326  return (
327    <McpUseProvider autoSize>
328      <div style={{ padding: 20 }}>
329        <input
330          type="text"
331          value={state.filters.search}
332          onChange={e => dispatch({ type: "SET_FILTER", key: "search", value: e.target.value })}
333          placeholder="Search..."
334        />
335 
336        <button onClick={() => dispatch({ type: "RESET" })}>
337          Reset Filters
338        </button>
339 
340        {/* ... render items with state */}
341      </div>
342    </McpUseProvider>
343  );
344}
345```
346 
347---
348 
349## Virtualization for Large Lists
350 
351Render only visible items:
352 
353```tsx
354import { useState, useRef, useEffect } from "react";
355import { McpUseProvider, useWidget } from "mcp-use/react";
356 
357export default function VirtualizedList() {
358  const { props, isPending } = useWidget();
359  const [scrollTop, setScrollTop] = useState(0);
360  const containerRef = useRef<HTMLDivElement>(null);
361 
362  const itemHeight = 50;
363  const containerHeight = 400;
364  const overscan = 3;
365 
366  if (isPending) {
367    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
368  }
369 
370  const visibleStart = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan);
371  const visibleEnd = Math.min(
372    props.items.length,
373    Math.ceil((scrollTop + containerHeight) / itemHeight) + overscan
374  );
375 
376  const visibleItems = props.items.slice(visibleStart, visibleEnd);
377 
378  return (
379    <McpUseProvider autoSize>
380      <div
381        ref={containerRef}
382        onScroll={e => setScrollTop(e.currentTarget.scrollTop)}
383        style={{
384          height: containerHeight,
385          overflow: "auto",
386          position: "relative"
387        }}
388      >
389        <div style={{ height: props.items.length * itemHeight, position: "relative" }}>
390          {visibleItems.map((item, index) => (
391            <div
392              key={item.id}
393              style={{
394                position: "absolute",
395                top: (visibleStart + index) * itemHeight,
396                height: itemHeight,
397                width: "100%",
398                padding: 12,
399                borderBottom: "1px solid #eee"
400              }}
401            >
402              {item.name}
403            </div>
404          ))}
405        </div>
406      </div>
407    </McpUseProvider>
408  );
409}
410```
411 
412---
413 
414## Debounced Search
415 
416> **Prerequisites:** For interactive widgets (buttons, forms, tool calls), read [interactivity.md](interactivity.md) first for foundational patterns.
417 
418Delay search to avoid excessive calls:
419 
420```tsx
421import { useState, useEffect } from "react";
422import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
423 
424function useDebounce<T>(value: T, delay: number): T {
425  const [debouncedValue, setDebouncedValue] = useState<T>(value);
426 
427  useEffect(() => {
428    const handler = setTimeout(() => {
429      setDebouncedValue(value);
430    }, delay);
431 
432    return () => {
433      clearTimeout(handler);
434    };
435  }, [value, delay]);
436 
437  return debouncedValue;
438}
439 
440export default function DebouncedSearchWidget() {
441  const { props, isPending } = useWidget();
442  const { callToolAsync } = useCallTool("search");
443  const [search, setSearch] = useState("");
444  const [results, setResults] = useState<{ id: string; name: string }[]>([]);
445  const [searching, setSearching] = useState(false);
446 
447  const debouncedSearch = useDebounce(search, 300);
448 
449  useEffect(() => {
450    if (!debouncedSearch.trim()) {
451      setResults([]);
452      return;
453    }
454 
455    setSearching(true);
456    callToolAsync({ query: debouncedSearch })
457      .then(result => setResults(result.structuredContent?.items || []))
458      .catch(err => console.error("Search failed:", err))
459      .finally(() => setSearching(false));
460  }, [debouncedSearch, callToolAsync]);
461 
462  if (isPending) {
463    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
464  }
465 
466  return (
467    <McpUseProvider autoSize>
468      <div style={{ padding: 20 }}>
469        <input
470          type="text"
471          value={search}
472          onChange={e => setSearch(e.target.value)}
473          placeholder="Search..."
474          style={{ width: "100%", padding: 8 }}
475        />
476 
477        {searching && <p>Searching...</p>}
478 
479        <div>
480          {results.map(item => (
481            <div key={item.id}>{item.name}</div>
482          ))}
483        </div>
484      </div>
485    </McpUseProvider>
486  );
487}
488```
489 
490---
491 
492## Infinite Scroll
493 
494Load more items as user scrolls:
495 
496```tsx
497import { useState, useRef, useEffect } from "react";
498import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
499 
500interface Item {
501  id: string;
502  name: string;
503}
504 
505export default function InfiniteScrollWidget() {
506  const { props, isPending } = useWidget<{ items: Item[] }>();
507  const { callToolAsync } = useCallTool("load-more");
508  const [items, setItems] = useState<Item[]>([]);
509  const [loading, setLoading] = useState(false);
510  const [hasMore, setHasMore] = useState(true);
511  const observerTarget = useRef<HTMLDivElement>(null);
512 
513  // Sync initial items from props once loaded
514  useEffect(() => {
515    if (!isPending && props.items) {
516      setItems(props.items);
517    }
518  }, [isPending, props.items]);
519 
520  useEffect(() => {
521    const observer = new IntersectionObserver(
522      entries => {
523        if (entries[0].isIntersecting && hasMore && !loading) {
524          loadMore();
525        }
526      },
527      { threshold: 1.0 }
528    );
529 
530    if (observerTarget.current) {
531      observer.observe(observerTarget.current);
532    }
533 
534    return () => observer.disconnect();
535  }, [hasMore, loading]);
536 
537  const loadMore = async () => {
538    setLoading(true);
539    try {
540      const result = await callToolAsync({
541        offset: items.length,
542        limit: 20
543      });
544 
545      const newItems = result.structuredContent?.items || [];
546      if (newItems.length === 0) {
547        setHasMore(false);
548      } else {
549        setItems(prev => [...prev, ...newItems]);
550      }
551    } catch (error) {
552      console.error("Failed to load more:", error);
553    } finally {
554      setLoading(false);
555    }
556  };
557 
558  if (isPending) {
559    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
560  }
561 
562  return (
563    <McpUseProvider autoSize>
564      <div style={{ padding: 20 }}>
565        {items.map(item => (
566          <div key={item.id} style={{ padding: 12, borderBottom: "1px solid #eee" }}>
567            {item.name}
568          </div>
569        ))}
570 
571        <div ref={observerTarget} style={{ height: 20 }}>
572          {loading && <p>Loading more...</p>}
573          {!hasMore && <p>No more items</p>}
574        </div>
575      </div>
576    </McpUseProvider>
577  );
578}
579```
580 
581---
582 
583## Local Storage Persistence
584 
585Persist widget state across sessions:
586 
587```tsx
588import { useState, useEffect } from "react";
589import { McpUseProvider, useWidget } from "mcp-use/react";
590 
591function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T) => void] {
592  const [storedValue, setStoredValue] = useState<T>(() => {
593    try {
594      const item = window.localStorage.getItem(key);
595      return item ? JSON.parse(item) : initialValue;
596    } catch (error) {
597      console.error("Error reading from localStorage:", error);
598      return initialValue;
599    }
600  });
601 
602  const setValue = (value: T) => {
603    try {
604      setStoredValue(value);
605      window.localStorage.setItem(key, JSON.stringify(value));
606    } catch (error) {
607      console.error("Error writing to localStorage:", error);
608    }
609  };
610 
611  return [storedValue, setValue];
612}
613 
614export default function PersistentWidget() {
615  const { props, isPending } = useWidget();
616  const [favorites, setFavorites] = useLocalStorage<string[]>("favorites", []);
617 
618  const toggleFavorite = (id: string) => {
619    setFavorites(prev =>
620      prev.includes(id) ? prev.filter(fav => fav !== id) : [...prev, id]
621    );
622  };
623 
624  if (isPending) {
625    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
626  }
627 
628  return (
629    <McpUseProvider autoSize>
630      <div>
631        {props.items.map(item => (
632          <div key={item.id}>
633            <button onClick={() => toggleFavorite(item.id)}>
634              {favorites.includes(item.id) ? "⭐" : "☆"}
635            </button>
636            {item.name}
637          </div>
638        ))}
639      </div>
640    </McpUseProvider>
641  );
642}
643```
644 
645---
646 
647## Drag and Drop
648 
649Reorder items with drag and drop:
650 
651```tsx
652import { useState, useEffect } from "react";
653import { McpUseProvider, useWidget } from "mcp-use/react";
654 
655interface Item {
656  id: string;
657  name: string;
658}
659 
660export default function DraggableList() {
661  const { props, isPending } = useWidget<{ items: Item[] }>();
662  const [items, setItems] = useState<Item[]>([]);
663  const [draggedIndex, setDraggedIndex] = useState<number | null>(null);
664 
665  // Sync items from props once loaded
666  useEffect(() => {
667    if (!isPending && props.items) {
668      setItems(props.items);
669    }
670  }, [isPending, props.items]);
671 
672  const handleDragStart = (index: number) => {
673    setDraggedIndex(index);
674  };
675 
676  const handleDragOver = (e: React.DragEvent, index: number) => {
677    e.preventDefault();
678 
679    if (draggedIndex === null || draggedIndex === index) return;
680 
681    const newItems = [...items];
682    const draggedItem = newItems[draggedIndex];
683 
684    newItems.splice(draggedIndex, 1);
685    newItems.splice(index, 0, draggedItem);
686 
687    setItems(newItems);
688    setDraggedIndex(index);
689  };
690 
691  const handleDragEnd = () => {
692    setDraggedIndex(null);
693    // Optionally save new order with useCallTool
694  };
695 
696  if (isPending) {
697    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
698  }
699 
700  return (
701    <McpUseProvider autoSize>
702      <div>
703        {items.map((item, index) => (
704          <div
705            key={item.id}
706            draggable
707            onDragStart={() => handleDragStart(index)}
708            onDragOver={e => handleDragOver(e, index)}
709            onDragEnd={handleDragEnd}
710            style={{
711              padding: 12,
712              margin: "4px 0",
713              backgroundColor: draggedIndex === index ? "#e3f2fd" : "white",
714              border: "1px solid #ddd",
715              cursor: "move"
716            }}
717          >
718            ⋮⋮ {item.name}
719          </div>
720        ))}
721      </div>
722    </McpUseProvider>
723  );
724}
725```
726 
727---
728 
729## Keyboard Shortcuts
730 
731```tsx
732import { useEffect } from "react";
733import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
734 
735export default function KeyboardWidget() {
736  const { props, isPending } = useWidget();
737  const { callTool: save } = useCallTool("save");
738 
739  useEffect(() => {
740    const handleKeyDown = (e: KeyboardEvent) => {
741      // Ctrl+S to save
742      if (e.ctrlKey && e.key === "s") {
743        e.preventDefault();
744        save({});
745      }
746 
747      // Escape to cancel
748      if (e.key === "Escape") {
749        // Handle escape
750      }
751 
752      // Arrow keys for navigation
753      if (e.key === "ArrowDown") {
754        // Navigate down
755      }
756    };
757 
758    window.addEventListener("keydown", handleKeyDown);
759    return () => window.removeEventListener("keydown", handleKeyDown);
760  }, [save]);
761 
762  if (isPending) {
763    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
764  }
765 
766  return (
767    <McpUseProvider autoSize>
768      <div>
769        <p>Keyboard shortcuts:</p>
770        <ul>
771          <li><kbd>Ctrl+S</kbd> - Save</li>
772          <li><kbd>Esc</kbd> - Cancel</li>
773          <li><kbd>↑/↓</kbd> - Navigate</li>
774        </ul>
775      </div>
776    </McpUseProvider>
777  );
778}
779```
780 
781---
782 
783## Best Practices
784 
7851. **Use Error Boundaries** - Catch errors gracefully
7862. **Memoize Expensive Computations** - Use `useMemo` for performance
7873. **Debounce User Input** - Avoid excessive API calls
7884. **Virtualize Large Lists** - Render only visible items
7895. **Persist State When Useful** - Use localStorage for preferences
7906. **Handle Loading States** - Show spinners, disable buttons
7917. **Implement Keyboard Shortcuts** - Improve power user experience
7928. **Profile Performance** - Use React DevTools Profiler
793 
794---
795 
796## Performance Checklist
797 
798- [ ] Large lists virtualized or paginated
799- [ ] Expensive computations memoized with `useMemo`
800- [ ] Event handlers memoized with `useCallback`
801- [ ] Search inputs debounced
802- [ ] Images lazy-loaded
803- [ ] Error boundaries in place
804- [ ] Console warnings addressed
805 
806---
807 
808## Next Steps
809 
810- **See examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
811- **Review best practices** → [../../SKILL.md](../../SKILL.md)
812