React UI Patterns

1---
2name: react-ui-patterns
3description: Modern React UI patterns for loading states, error handling, and data fetching. Use when building UI components, handling async data, or managing UI states.
4---
5 
6# React UI Patterns
7 
8## Core Principles
9 
101. **Never show stale UI** - Loading spinners only when actually loading
112. **Always surface errors** - Users must know when something fails
123. **Optimistic updates** - Make the UI feel instant
134. **Progressive disclosure** - Show content as it becomes available
145. **Graceful degradation** - Partial data is better than no data
15 
16## Loading State Patterns
17 
18### The Golden Rule
19 
20**Show loading indicator ONLY when there's no data to display.**
21 
22```typescript
23// CORRECT - Only show loading when no data exists
24const { data, loading, error } = useGetItemsQuery();
25 
26if (error) return <ErrorState error={error} onRetry={refetch} />;
27if (loading && !data) return <LoadingState />;
28if (!data?.items.length) return <EmptyState />;
29 
30return <ItemList items={data.items} />;
31```
32 
33```typescript
34// WRONG - Shows spinner even when we have cached data
35if (loading) return <LoadingState />; // Flashes on refetch!
36```
37 
38### Loading State Decision Tree
39 
40```
41Is there an error?
42  → Yes: Show error state with retry option
43  → No: Continue
44 
45Is it loading AND we have no data?
46  → Yes: Show loading indicator (spinner/skeleton)
47  → No: Continue
48 
49Do we have data?
50  → Yes, with items: Show the data
51  → Yes, but empty: Show empty state
52  → No: Show loading (fallback)
53```
54 
55### Skeleton vs Spinner
56 
57| Use Skeleton When | Use Spinner When |
58|-------------------|------------------|
59| Known content shape | Unknown content shape |
60| List/card layouts | Modal actions |
61| Initial page load | Button submissions |
62| Content placeholders | Inline operations |
63 
64## Error Handling Patterns
65 
66### The Error Handling Hierarchy
67 
68```
691. Inline error (field-level) → Form validation errors
702. Toast notification → Recoverable errors, user can retry
713. Error banner → Page-level errors, data still partially usable
724. Full error screen → Unrecoverable, needs user action
73```
74 
75### Always Show Errors
76 
77**CRITICAL: Never swallow errors silently.**
78 
79```typescript
80// CORRECT - Error always surfaced to user
81const [createItem, { loading }] = useCreateItemMutation({
82  onCompleted: () => {
83    toast.success({ title: 'Item created' });
84  },
85  onError: (error) => {
86    console.error('createItem failed:', error);
87    toast.error({ title: 'Failed to create item' });
88  },
89});
90 
91// WRONG - Error silently caught, user has no idea
92const [createItem] = useCreateItemMutation({
93  onError: (error) => {
94    console.error(error); // User sees nothing!
95  },
96});
97```
98 
99### Error State Component Pattern
100 
101```typescript
102interface ErrorStateProps {
103  error: Error;
104  onRetry?: () => void;
105  title?: string;
106}
107 
108const ErrorState = ({ error, onRetry, title }: ErrorStateProps) => (
109  <div className="error-state">
110    <Icon name="exclamation-circle" />
111    <h3>{title ?? 'Something went wrong'}</h3>
112    <p>{error.message}</p>
113    {onRetry && (
114      <Button onClick={onRetry}>Try Again</Button>
115    )}
116  </div>
117);
118```
119 
120## Button State Patterns
121 
122### Button Loading State
123 
124```tsx
125<Button
126  onClick={handleSubmit}
127  isLoading={isSubmitting}
128  disabled={!isValid || isSubmitting}
129>
130  Submit
131</Button>
132```
133 
134### Disable During Operations
135 
136**CRITICAL: Always disable triggers during async operations.**
137 
138```tsx
139// CORRECT - Button disabled while loading
140<Button
141  disabled={isSubmitting}
142  isLoading={isSubmitting}
143  onClick={handleSubmit}
144>
145  Submit
146</Button>
147 
148// WRONG - User can tap multiple times
149<Button onClick={handleSubmit}>
150  {isSubmitting ? 'Submitting...' : 'Submit'}
151</Button>
152```
153 
154## Empty States
155 
156### Empty State Requirements
157 
158Every list/collection MUST have an empty state:
159 
160```tsx
161// WRONG - No empty state
162return <FlatList data={items} />;
163 
164// CORRECT - Explicit empty state
165return (
166  <FlatList
167    data={items}
168    ListEmptyComponent={<EmptyState />}
169  />
170);
171```
172 
173### Contextual Empty States
174 
175```tsx
176// Search with no results
177<EmptyState
178  icon="search"
179  title="No results found"
180  description="Try different search terms"
181/>
182 
183// List with no items yet
184<EmptyState
185  icon="plus-circle"
186  title="No items yet"
187  description="Create your first item"
188  action={{ label: 'Create Item', onClick: handleCreate }}
189/>
190```
191 
192## Form Submission Pattern
193 
194```tsx
195const MyForm = () => {
196  const [submit, { loading }] = useSubmitMutation({
197    onCompleted: handleSuccess,
198    onError: handleError,
199  });
200 
201  const handleSubmit = async () => {
202    if (!isValid) {
203      toast.error({ title: 'Please fix errors' });
204      return;
205    }
206    await submit({ variables: { input: values } });
207  };
208 
209  return (
210    <form>
211      <Input
212        value={values.name}
213        onChange={handleChange('name')}
214        error={touched.name ? errors.name : undefined}
215      />
216      <Button
217        type="submit"
218        onClick={handleSubmit}
219        disabled={!isValid || loading}
220        isLoading={loading}
221      >
222        Submit
223      </Button>
224    </form>
225  );
226};
227```
228 
229## Anti-Patterns
230 
231### Loading States
232 
233```typescript
234// WRONG - Spinner when data exists (causes flash)
235if (loading) return <Spinner />;
236 
237// CORRECT - Only show loading without data
238if (loading && !data) return <Spinner />;
239```
240 
241### Error Handling
242 
243```typescript
244// WRONG - Error swallowed
245try {
246  await mutation();
247} catch (e) {
248  console.log(e); // User has no idea!
249}
250 
251// CORRECT - Error surfaced
252onError: (error) => {
253  console.error('operation failed:', error);
254  toast.error({ title: 'Operation failed' });
255}
256```
257 
258### Button States
259 
260```typescript
261// WRONG - Button not disabled during submission
262<Button onClick={submit}>Submit</Button>
263 
264// CORRECT - Disabled and shows loading
265<Button onClick={submit} disabled={loading} isLoading={loading}>
266  Submit
267</Button>
268```
269 
270## Checklist
271 
272Before completing any UI component:
273 
274**UI States:**
275- [ ] Error state handled and shown to user
276- [ ] Loading state shown only when no data exists
277- [ ] Empty state provided for collections
278- [ ] Buttons disabled during async operations
279- [ ] Buttons show loading indicator when appropriate
280 
281**Data & Mutations:**
282- [ ] Mutations have onError handler
283- [ ] All user actions have feedback (toast/visual)
284 
285## Integration with Other Skills
286 
287- **graphql-schema**: Use mutation patterns with proper error handling
288- **testing-patterns**: Test all UI states (loading, error, empty, success)
289- **formik-patterns**: Apply form submission patterns
290