react

Requirements

• Always use destructured props in function parameters
• Define TypeScript types inline with the destructured props
• Avoid creating separate interfaces for component props
• Avoid non-destructured props that require additional destructuring inside the component
• Use available UI components from the component library
• Use CSS variables from globals.css for consistent theming
• Use Tailwind v4 syntax (see Tailwind v4 Syntax)
• DO NOT add icon margin in Button, DropdownMenuItem: use gap-2 instead
• Use useEffectEvent to extract non-reactive logic from Effects (see Separating Events from Effects)
• NEVER suppress the dependency linter with eslint-disable - use useEffectEvent instead
• Use custom breakpoint syntax for responsive design (see App-Specific Rules)

Tailwind v4 Syntax

• Inline opacity: Use / for opacity (bg-black/50 text-white/80)
  • v3: bg-black bg-opacity-50 text-white text-opacity-80
  • Removed: bg-opacity-*, text-opacity-*, border-opacity-*
• Renamed utilities: shadow-sm → shadow-xs, rounded-sm → rounded-xs, blur-sm → blur-xs
• CSS variables: Use parentheses bg-(--brand-color) instead of brackets bg-[--brand-color]
• Important modifier: Exclamation mark at the end (size-5!) instead of beginning (!size-5)
• Descendant selectors: Use **: for all descendants (replaces [&_*]:) and *: for direct children (replaces [&>*]:)
  • All descendants: **:px-4 instead of [&_*]:px-4
  • Direct children: *:px-4 instead of [&>*]:px-4
  • Element filtering: *:[a]:underline instead of [&>a]:underline, **:[a]:underline instead of [&_a]:underline
  • Data attributes: *:data-[slot=field-label]:flex-auto instead of *:[[data-slot=field-label]]:flex-auto. Keep [[data-...]] if there are other selectors.
  • Context-aware (in-): in-data-[slot=tooltip-content]:text-background instead of [[data-slot=tooltip-content]_&]:text-background
• Composable variants: Chain variants together (group-has-data-selected:opacity-100, data-highlighted:ring-2)
• Canonical classes: Always prefer built-in utilities over arbitrary values (e.g., w-full instead of w-[100%], translate-x-full instead of translate-x-[100%])
• Default changes: Border color now currentColor (was gray-200), ring width now 1px (was 3px)

Component Patterns

Design Tokens

Design tokens are semantic CSS variables that separate theme, context, and usage. Rather than hardcoding colors, use a semantic naming convention that creates layers of abstraction.

Variable Architecture

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
}

Common tokens:

• --background - Page background color
• --foreground - General text color
• --primary - Main brand color
• --primary-foreground - Text color against primary

This creates a maintainable, flexible system that scales across applications.

Data Attribute Styling Patterns

Shadcn/ui and Radix UI components use data attributes (data-state, data-slot) to enable flexible styling without prop explosion. Use these patterns when working with components that expose data attributes.

Styling with data-state

Components expose their state through data-state attributes. Use Tailwind's arbitrary variant syntax to style based on component state:

<Dialog
  className={cn(
    // Base styles
    "rounded-lg border p-4",
    // State-based styles
    "data-[state=open]:animate-in data-[state=open]:fade-in",
    "data-[state=closed]:animate-out data-[state=closed]:fade-out",
    // Multiple attributes
    "data-[state=open][data-side=top]:slide-in-from-top-2",
  )}
/>

For commonly-used states, extend Tailwind's configuration:

module.exports = {
  theme: {
    extend: {
      data: {
        open: 'state="open"',
        closed: 'state="closed"',
        active: 'state="active"',
      },
    },
  },
};

Then use shorthand:

<Dialog className="data-open:opacity-100 data-closed:opacity-0" />

Radix UI Data Attributes

Radix UI automatically applies data attributes to its primitives:

import * as Dialog from "@radix-ui/react-dialog";

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    {/* Radix automatically adds data-state="open" | "closed" */}
    <Dialog.Overlay className="data-[state=open]:animate-in data-[state=closed]:animate-out" />
    <Dialog.Content className="data-[state=open]:fade-in data-[state=closed]:fade-out" />
  </Dialog.Portal>
</Dialog.Root>;

Common Radix data attributes:

• data-state - open/closed, active/inactive, on/off
• data-side - top/right/bottom/left (for positioned elements)
• data-align - start/center/end (for positioned elements)
• data-orientation - horizontal/vertical
• data-disabled - present when disabled
• data-placeholder - present when showing placeholder

Common State Patterns

Use data attributes for all kinds of component state:

// Open/closed state
<Accordion data-state={isOpen ? 'open' : 'closed'} />

// Selected state
<Tab data-state={isSelected ? 'active' : 'inactive'} />

// Disabled state (in addition to disabled attribute)
<Button data-disabled={isDisabled} disabled={isDisabled} />

// Loading state
<Button data-loading={isLoading} />

// Orientation
<Slider data-orientation="horizontal" />

// Side/position
<Tooltip data-side="top" />

Using data-slot for Component Targeting

Components use data-slot attributes for stable identifiers that can be targeted by parents.

Using has-[] for parent-aware styling:

<form
  data-slot="form"
  className={cn(
    "space-y-4",
    // Adjust spacing when specific slots are present
    "has-[>[data-slot=form-section]]:space-y-6",
    "has-[>[data-slot=inline-fields]]:space-y-2",
    // Style based on slot states
    "has-[[data-slot=submit-button][data-loading=true]]:opacity-50",
  )}
>
  {children}
</form>

Using [&_] for descendant targeting:

<div
  data-slot="card"
  className={cn(
    "rounded-lg border p-4",
    // Target any descendant with data-slot
    "[&_[data-slot=card-header]]:mb-4",
    "[&_[data-slot=card-title]]:text-lg [&_[data-slot=card-title]]:font-semibold",
    "[&_[data-slot=card-description]]:text-muted-foreground [&_[data-slot=card-description]]:text-sm",
    "[&_[data-slot=card-footer]]:mt-4 [&_[data-slot=card-footer]]:border-t [&_[data-slot=card-footer]]:pt-4",
  )}
>
  {children}
</div>

Global CSS with data-slot

Use global CSS for theme-wide component styling:

/* Style all buttons within forms */
[data-slot="form"] [data-slot="button"] {
  @apply w-full @xl:w-auto;
}

/* Style submit buttons specifically */
[data-slot="form"] [data-slot="submit-button"] {
  @apply bg-primary text-primary-foreground;
}

/* Adjust inputs within inline layouts */
[data-slot="inline-fields"] [data-slot="input"] {
  @apply flex-1;
}

/* Style based on state combinations */
[data-slot="dialog"][data-state="open"] [data-slot="dialog-content"] {
  @apply animate-in fade-in;
}

data-slot Naming Conventions

Follow these conventions for consistent data-slot naming:

1. Use kebab-case - data-slot="form-field" not data-slot="formField"
2. Be specific - data-slot="submit-button" not data-slot="button"
3. Match component purpose - Name reflects what it does, not how it looks
4. Avoid implementation details - data-slot="user-avatar" not data-slot="rounded-image"

// ✅ Good examples
data-slot="search-input"
data-slot="navigation-menu"
data-slot="error-message"
data-slot="submit-button"
data-slot="card-header"

// ❌ Avoid
data-slot="input"           // Too generic
data-slot="blueButton"      // Includes styling
data-slot="div-wrapper"     // Implementation detail
data-slot="mainContent"     // Use kebab-case

When to Use Data Attributes vs Props

Use data-state for:

• Visual states (open/closed, active/inactive, loading)
• Layout states (orientation, side, alignment)
• Interaction states (hover, focus, disabled when styling children)

Use data-slot for:

• Component identification with stable identifiers
• Parent-child composition patterns
• Theme-wide component styling
• Variant-independent targeting

Use props for:

• Variants (primary, secondary, destructive)
• Sizes (sm, md, lg)
• Behavioral configuration (controlled/uncontrolled, defaults)
• Event handlers (onClick, onChange)

Combined example:

const Button = ({ variant = 'primary', size = 'md', loading, disabled, className, ...props }) => (
  <button
    data-slot="button"
    data-loading={loading}
    data-disabled={disabled}
    className={cn(buttonVariants({ variant, size }), className)}
    disabled={disabled}
    {...props}
  />
);

// Usage
<Button variant="primary" size="lg">Submit</Button>
<form className="[&_[data-slot=button]]:w-full"><Button>Submit</Button></form>
<Button loading={isLoading} className="data-[loading=true]:opacity-50">Submit</Button>

React Compiler

Context

This project uses React Compiler, which automatically optimizes your React code through automatic memoization at build time. Manual memoization with useMemo, useCallback, and React.memo is rarely needed and often introduces unnecessary complexity.

Core Principle

Write clean, idiomatic React code. Let the compiler optimize it.

React Compiler automatically applies optimal memoization based on data flow analysis. It can even optimize cases that manual memoization cannot handle, such as memoizing values after conditional returns or within complex control flow.

Requirements

DO NOT Use Manual Memoization

• NEVER wrap components with React.memo unless you have a specific, documented reason
• NEVER use useMemo for performance optimization - the compiler handles this
• NEVER use useCallback for performance optimization - the compiler handles this
• NEVER create inline functions and then wrap them in useCallback - this is redundant

When Manual Memoization IS Acceptable

Manual memoization should only be used as an escape hatch for precise control in specific scenarios:

1. Effect Dependencies: When a memoized value is used as a dependency in useEffect to prevent unnecessary effect re-runs
2. External Library Integration: When passing callbacks to non-React libraries that don't handle reference changes well
3. Precise Control: When you have profiled and verified that the compiler's automatic memoization is insufficient for a specific hotspot

CRITICAL: If you use manual memoization, you MUST document why with a comment explaining the specific reason.

Examples

Component Memoization

const handleClick = (item) => { onClick(item.id); };

return (

The compiler automatically memoizes components and values, ensuring optimal re-rendering without manual intervention.
</example>

<example type="invalid">
```tsx
// ❌ Avoid - Unnecessary manual memoization
const ExpensiveComponent = memo(function ExpensiveComponent({ data, onClick }) {
  const processedData = useMemo(() => {
    return expensiveProcessing(data);
  }, [data]);

  const handleClick = useCallback((item) => {
    onClick(item.id);
  }, [onClick]);

  return (
    <div>
      {processedData.map(item => (
        <Item key={item.id} onClick={() => handleClick(item)} />
      ))}
    </div>
  );
});

This manual memoization is redundant with React Compiler and adds unnecessary complexity.

Event Handlers

return (

The compiler optimizes this correctly without `useCallback`.
</example>

<example type="invalid">
```tsx
// ❌ Avoid - Unnecessary useCallback
function TodoList({ todos, onToggle }) {
  const handleToggle = useCallback((id) => {
    onToggle(id);
  }, [onToggle]);

  return (
    <ul>
      {todos.map(todo => (
        <TodoItem
          key={todo.id}
          todo={todo}
          onToggle={() => handleToggle(todo.id)}
        />
      ))}
    </ul>
  );
}

The useCallback is unnecessary and creates a subtle bug: the inline arrow function () => handleToggle(todo.id) creates a new function on every render anyway, breaking the memoization.

Computed Values

See Derived State for the pattern. Compute inline during render; React Compiler handles memoization.

Conditional Memoization

// The compiler memoizes this even after the conditional return const mergedTheme = mergeTheme(theme, defaultTheme);

return ( <ThemeContext.Provider value={mergedTheme}> {children} </ThemeContext.Provider> ); }

The compiler can memoize values after conditional returns, which is impossible with manual memoization.
</example>

<example type="invalid">
```tsx
// ❌ Avoid - Attempting manual memoization with early returns
function ThemeProvider({ children, theme }) {
  const mergedTheme = useMemo(
    () => mergeTheme(theme, defaultTheme),
    [theme]
  );

  if (!children) {
    return null;
  }

  return (
    <ThemeContext.Provider value={mergedTheme}>
      {children}
    </ThemeContext.Provider>
  );
}

This forces the expensive merge to run even when returning null, whereas the compiler optimizes this correctly.

Acceptable Use Case: Effect Dependencies

useEffect(() => { fetchData(stableFilters); }, [stableFilters]);

// ... }

This is an acceptable escape hatch with a clear, documented reason.
</example>

### Acceptable Use Case: External Library Integration

<example>
```tsx
// ✅ Acceptable - useCallback for third-party library
function MapComponent({ markers, onMarkerClick }) {
  // Documented reason: GoogleMaps library doesn't handle reference changes well
  // and re-attaches all event listeners on every render
  const handleMarkerClick = useCallback((marker) => {
    onMarkerClick(marker.id);
  }, [onMarkerClick]);

  useEffect(() => {
    markers.forEach(marker => {
      googleMapsApi.addClickListener(marker, handleMarkerClick);
    });
  }, [markers, handleMarkerClick]);

  // ...
}

This is an acceptable escape hatch for external library integration.

Effects

Principle

• Treat Effects as an escape hatch for synchronizing React with external systems (DOM APIs, network, imperative libraries). If no external system is involved, keep the logic in render or event handlers.
• Rendering must stay pure. Event-driven work (buying, saving, submitting) belongs in the handler that caused it, not in an Effect.
• React Compiler assumes idiomatic React semantics. Avoid manual memoization tricks to influence dependency stability; rely on actual values and let the compiler hoist what it can.
• For mixing reactive and non-reactive logic, see Separating Events from Effects for useEffectEvent patterns.

When to Add an Effect

• Bridging React state to imperative APIs (media playback, map widgets, modals) where you must call imperative methods after paint.
• Subscribing to external stores or browser events; prefer useSyncExternalStore when possible so React manages resubscription for you.
• Performing work that must run because the component is visible (e.g., logging an analytics impression) with an understanding that it will run twice in development.

When Not to Add an Effect

• Deriving or filtering data for rendering. See Derived State.
• Resetting or coordinating state between components. Use keys, derive state from props, or lift state up instead of chaining Effects.
• Handling user interactions. Run imperative logic inside the event handler so React can batch updates and you avoid double execution.
• Preventing Strict Mode double-invocation. Never guard Effects with refs or flags to stop re-execution; fix the underlying cleanup instead.

Derived State: Compute During Render, Not in Effects

The most common unnecessary Effect is transforming data for rendering. When you have data that can be computed from props or state, compute it directly during render:

useEffect(() => { setFiltered(items.filter(item => item.status === filter)); }, [items, filter]);

return ; }

// ✅ Correct: Compute during render function FilteredList({ items, filter }) { const filtered = items.filter(item => item.status === filter); return ; }

</example>

**Why this matters**: The Effect pattern causes an extra render pass with stale data, wastes cycles, and can cause visual flicker.

### When setState in Effect IS Valid

setState in an Effect is valid when the value **comes from an external source** that React can't observe:

1. **DOM measurements** - Reading element dimensions after paint
2. **External subscriptions** - Browser APIs, WebSocket, third-party stores
3. **Resources with cleanup** - Object URLs, media streams, connections

<example>
```tsx
// ✅ Valid: DOM measurement after paint
function Tooltip({ children }) {
  const ref = useRef<HTMLDivElement>(null);
  const [height, setHeight] = useState(0);

  useLayoutEffect(() => {
    if (ref.current) {
      setHeight(ref.current.getBoundingClientRect().height);
    }
  }, []);

  return <div ref={ref}>{children}</div>;
}

// ✅ Valid: External subscription
function OnlineStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handler = () => setIsOnline(navigator.onLine);
    window.addEventListener('online', handler);
    window.addEventListener('offline', handler);
    return () => {
      window.removeEventListener('online', handler);
      window.removeEventListener('offline', handler);
    };
  }, []);

  return <span>{isOnline ? 'Online' : 'Offline'}</span>;
}

// ✅ Valid: Resource with cleanup (Object URL)
function ImagePreview({ file }: { file: File }) {
  const objectUrl = useMemo(() => URL.createObjectURL(file), [file]);

  useEffect(() => {
    return () => URL.revokeObjectURL(objectUrl);
  }, [objectUrl]);

  return <img src={objectUrl} alt={file.name} />;
}

Ref Access Rules

Never read or write ref.current during render except for lazy initialization:

// ❌ Invalid: Writing ref during render function Component({ value }) { const ref = useRef(null); ref.current = value; // Don't write during render! return ; }

// ✅ Valid: Read/write in Effects or handlers function Component() { const ref = useRef(null);

useEffect(() => { if (ref.current) { console.log(ref.current.offsetWidth); // OK in effect } }, []);

const handleClick = () => { console.log(ref.current); // OK in handler };

return ; }

// ✅ Valid: Lazy initialization (read-then-write once) function Component() { const ref = useRef<ExpensiveValue | null>(null);

if (ref.current === null) { ref.current = createExpensiveValue(); // OK - one-time init }

return ; }

</example>

### Decision Tree: Derived State vs Effects vs Refs

Need to transform/filter/derive data for display? ├─ YES → Compute during render (no useState, no useEffect) │ const derived = items.filter(x => x.active); │ ├─ Need to cache expensive computation? │ └─ Let React Compiler handle it, or useMemo if profiled bottleneck │ Need to sync with external system (DOM, network, browser API)? ├─ YES → useEffect with setState IS valid │ useEffect(() => { setHeight(ref.current.offsetHeight) }, []) │ Need to read ref.current? ├─ During render → ❌ NEVER (except lazy init) ├─ In Effect → ✅ OK ├─ In handler → ✅ OK │ Need to sync file/blob/stream with cleanup? └─ useMemo for creation + useEffect for cleanup const url = useMemo(() => URL.createObjectURL(file), [file]); useEffect(() => () => URL.revokeObjectURL(url), [url]);

### Red Flags - STOP Before "Fixing"

If you're about to:
- Replace `useState + useEffect` with `useMemo` that reads `ref.current` → STOP
- Add `eslint-disable` for either rule → STOP, use decision tree
- "Fix" one error and immediately get the other → STOP, you're cycling

### Rationalization Table

| Excuse | Reality |
|--------|---------|
| "useMemo fixes derived state" | Only if you don't read refs during render |
| "I'll read ref in useMemo since it runs during render" | useMemo IS render. Ref rules still apply. |
| "Effect was the problem" | Maybe, but check if you're now violating ref rules |
| "This is simple, I know what to do" | The cycle happens because you skip the decision tree |

### Cleanup and Strict Mode

- Always return a cleanup when the Effect allocates resources (connections, listeners, timers). React calls cleanup before re-running the Effect and on unmount.
- Expect every Effect to mount → cleanup → mount in development. Production runs once, but development ensures your Effect is resilient.
- Avoid side-stepping cleanup by storing mutable singletons in refs. This leaves background work running across navigations and breaks invariants.

### React Compiler Considerations

- Because the compiler stabilizes values for you, do not introduce `useMemo`/`useCallback` purely to satisfy Effect dependency linting. Refactor the Effect so it depends on real inputs.
- Let the dependency array express actual inputs. Suppressing ESLint warnings or omitting deps makes compiler output unreliable.
- Prefer custom hooks (`useData`, `useOnlineStatus`) to bundle complex Effect logic once. This keeps call sites simple and lets the compiler optimize the hook body.

<example>
```tsx
// ✅ Effect that syncs with an external API and cleans up
export function VideoPlayer({ src, isPlaying }: Props) {
  const ref = useRef<HTMLVideoElement | null>(null);

useEffect(() => {
const node = ref.current;
if (!node) {
return;
}

    if (isPlaying) {
      void node.play();
    } else {
      node.pause();
    }

    return () => {
      node.pause();
    };

}, [isPlaying]);

return <video ref={ref} src={src} playsInline loop />;
}