DEV Community: Thoithoi Shougrakpam

You Might Not Need an Effect - Study Guide

Thoithoi Shougrakpam — Mon, 30 Mar 2026 17:30:20 +0000

Source: https://react.dev/learn/you-might-not-need-an-effect

Core Principle

Effects are an escape hatch from the React paradigm. They let you "step outside" of React and synchronize your components with external systems like:

Non-React widgets
Network
Browser DOM

If there is no external system involved (for example, if you want to update a component's state when some props or state change), you shouldn't need an Effect.

Removing unnecessary Effects will make your code:

✅ Easier to follow
✅ Faster to run
✅ Less error-prone

When You DON'T Need Effects

1. Transforming Data for Rendering

❌ Bad: Using Effect to update state

function Form() {
  const [firstName, setFirstName] = useState('Taylor');
  const [lastName, setLastName] = useState('Swift');

  // 🔴 Avoid: redundant state and unnecessary Effect
  const [fullName, setFullName] = useState('');
  useEffect(() => {
    setFullName(firstName + ' ' + lastName);
  }, [firstName, lastName]);
}

Problem: This does an entire render pass with a stale value, then immediately re-renders with the updated value.

✅ Good: Calculate during rendering

function Form() {
  const [firstName, setFirstName] = useState('Taylor');
  const [lastName, setLastName] = useState('Swift');
  // ✅ Good: calculated during rendering
  const fullName = firstName + ' ' + lastName;
}

When something can be calculated from existing props or state, don't put it in state. Calculate it during rendering instead.

2. Caching Expensive Calculations

❌ Bad: Using Effect with state

function TodoList({ todos, filter }) {
  const [newTodo, setNewTodo] = useState('');

  // 🔴 Avoid: redundant state and unnecessary Effect
  const [visibleTodos, setVisibleTodos] = useState([]);
  useEffect(() => {
    setVisibleTodos(getFilteredTodos(todos, filter));
  }, [todos, filter]);
}

✅ Good: Use useMemo for expensive calculations

function TodoList({ todos, filter }) {
  const [newTodo, setNewTodo] = useState('');

  // ✅ Does not re-run unless todos or filter change
  const visibleTodos = useMemo(() => {
    return getFilteredTodos(todos, filter);
  }, [todos, filter]);
}

Or even simpler if the calculation is not expensive:

const visibleTodos = getFilteredTodos(todos, filter);

The function you wrap in useMemo runs during rendering, so this only works for pure calculations.

3. Resetting All State When a Prop Changes

❌ Bad: Using Effect to reset state

export default function ProfilePage({ userId }) {
  const [comment, setComment] = useState('');

  // 🔴 Avoid: Resetting state on prop change in an Effect
  useEffect(() => {
    setComment('');
  }, [userId]);
}

Problem: This is inefficient because ProfilePage and its children will first render with the stale value, and then render again.

✅ Good: Use a key to reset state

export default function ProfilePage({ userId }) {
  return (
    <Profile
      userId={userId}
      key={userId} // ✅ This and any other state below will reset on key change automatically
    />
  );
}

function Profile({ userId }) {
  const [comment, setComment] = useState('');
  // ...
}

By passing userId as a key, you're asking React to treat two Profile components with different userId as two different components that should not share any state.

4. Adjusting Some State When a Prop Changes

❌ Bad: Using Effect to sync derived state

function List({ items }) {
  const [isReverse, setIsReverse] = useState(false);
  const [selection, setSelection] = useState(null);

  // 🔴 Avoid: Adjusting state on prop change in an Effect
  useEffect(() => {
    setSelection(null);
  }, [items]);
}

✅ Better: Adjust state during rendering

function List({ items }) {
  const [isReverse, setIsReverse] = useState(false);
  const [selection, setSelection] = useState(null);

  // ✅ Best: Calculate everything during rendering
  const [prevItems, setPrevItems] = useState(items);
  if (items !== prevItems) {
    setPrevItems(items);
    setSelection(null);
  }
}

✅ Best: Calculate everything during rendering

function List({ items }) {
  const [isReverse, setIsReverse] = useState(false);
  const [selectedId, setSelectedId] = useState(null);

  // ✅ Best: Calculate everything during rendering
  const selection = items.find(item => item.id === selectedId) ?? null;
}

Storing information from previous renders can be hard to understand, but it's better than updating the same state in an Effect. Always check whether you can reset all state with a key or calculate everything during rendering instead.

5. Sharing Logic Between Event Handlers

❌ Bad: Using Effect for event-specific logic

function ProductPage({ product, addToCart }) {
  // 🔴 Avoid: Event-specific logic inside an Effect
  useEffect(() => {
    if (product.isInCart) {
      showNotification(`Added ${product.name} to the shopping cart!`);
    }
  }, [product]);

  function handleBuyClick() {
    addToCart(product);
  }

  function handleCheckoutClick() {
    addToCart(product);
    navigateTo('/checkout');
  }
}

Problem: This Effect is unnecessary and will cause bugs. The notification will appear every time the page reloads if the product is already in the cart.

✅ Good: Extract shared logic into a function

function ProductPage({ product, addToCart }) {
  // ✅ Good: Event-specific logic is called from event handlers
  function buyProduct() {
    addToCart(product);
    showNotification(`Added ${product.name} to the shopping cart!`);
  }

  function handleBuyClick() {
    buyProduct();
  }

  function handleCheckoutClick() {
    buyProduct();
    navigateTo('/checkout');
  }
}

Key Question: Ask yourself whether some code should be in an Effect or in an event handler:

Event Handler: If this logic is caused by a particular interaction
Effect: If it's caused by the user seeing the component on the screen

6. Sending POST Requests

❌ Bad: Form submission in Effect

function Form() {
  const [firstName, setFirstName] = useState('');
  const [lastName, setLastName] = useState('');

  // 🔴 Avoid: Event-specific logic inside an Effect
  const [jsonToSubmit, setJsonToSubmit] = useState(null);
  useEffect(() => {
    if (jsonToSubmit !== null) {
      post('/api/register', jsonToSubmit);
    }
  }, [jsonToSubmit]);

  function handleSubmit(e) {
    e.preventDefault();
    setJsonToSubmit({ firstName, lastName });
  }
}

✅ Good: Analytics in Effect, form submission in event handler

function Form() {
  const [firstName, setFirstName] = useState('');
  const [lastName, setLastName] = useState('');

  // ✅ Good: This logic should run because the component was displayed
  useEffect(() => {
    post('/analytics/event', { eventName: 'visit_form' });
  }, []);

  function handleSubmit(e) {
    e.preventDefault();
    // ✅ Good: Event-specific logic is in the event handler
    post('/api/register', { firstName, lastName });
  }
}

Use Effects only for code that should run because the component was displayed to the user.

7. Chains of Computations

❌ Bad: Chaining Effects

function Game() {
  const [card, setCard] = useState(null);
  const [goldCardCount, setGoldCardCount] = useState(0);
  const [round, setRound] = useState(1);
  const [isGameOver, setIsGameOver] = useState(false);

  // 🔴 Avoid: Chains of Effects that adjust the state solely to trigger each other
  useEffect(() => {
    if (card !== null && card.gold) {
      setGoldCardCount(c => c + 1);
    }
  }, [card]);

  useEffect(() => {
    if (goldCardCount > 3) {
      setRound(r => r + 1);
      setGoldCardCount(0);
    }
  }, [goldCardCount]);

  useEffect(() => {
    if (round > 5) {
      setIsGameOver(true);
    }
  }, [round]);

  useEffect(() => {
    alert('Good game!');
  }, [isGameOver]);
}

Problems:

Very inefficient: component re-renders between each set call
Rigid and fragile: hard to evolve as requirements change

✅ Good: Calculate during rendering, update in event handler

function Game() {
  const [card, setCard] = useState(null);
  const [goldCardCount, setGoldCardCount] = useState(0);
  const [round, setRound] = useState(1);

  // ✅ Calculate what you can during rendering
  const isGameOver = round > 5;

  function handlePlaceCard(nextCard) {
    if (isGameOver) {
      throw Error('Game already ended.');
    }

    // ✅ Calculate all the next state in the event handler
    setCard(nextCard);
    if (nextCard.gold) {
      if (goldCardCount <= 3) {
        setGoldCardCount(goldCardCount + 1);
      } else {
        setGoldCardCount(0);
        setRound(round + 1);
        if (round === 5) {
          alert('Good game!');
        }
      }
    }
  }
}

This is a lot more efficient. Also, if you implement a way to view game history, you can set each state variable to a move from the past without triggering the Effect chain.

8. Initializing the Application

❌ Bad: App initialization in Effect

function App() {
  // 🔴 Avoid: Effects with logic that should only ever run once
  useEffect(() => {
    loadDataFromLocalStorage();
    checkAuthToken();
  }, []);
}

Problem: This will run twice in development, which can cause issues (e.g., invalidating authentication token).

✅ Good: Top-level initialization

if (typeof window !== 'undefined') { // Check if we're running in the browser
  checkAuthToken();
  loadDataFromLocalStorage();
}

function App() {
  // ...
}

✅ Alternative: Use a flag

let didInit = false;

function App() {
  useEffect(() => {
    if (!didInit) {
      didInit = true;
      // ✅ Only runs once per app load
      loadDataFromLocalStorage();
      checkAuthToken();
    }
  }, []);
}

Code at the top level runs once when your component is imported—even if it doesn't end up being rendered.

9. Notifying Parent Components About State Changes

❌ Bad: Using Effect to call parent's onChange

function Toggle({ onChange }) {
  const [isOn, setIsOn] = useState(false);

  // 🔴 Avoid: The onChange handler runs too late
  useEffect(() => {
    onChange(isOn);
  }, [isOn, onChange]);

  function handleClick() {
    setIsOn(!isOn);
  }
}

Problem: The Toggle updates its state first, and React updates the screen. Then React runs the Effect, which calls the onChange function passed from a parent component. Now the parent component will update its own state, starting another render pass.

✅ Good: Update both in the same event handler

function Toggle({ onChange }) {
  const [isOn, setIsOn] = useState(false);

  function updateToggle(nextIsOn) {
    // ✅ Good: Perform all updates during the event that caused them
    setIsOn(nextIsOn);
    onChange(nextIsOn);
  }

  function handleClick() {
    updateToggle(!isOn);
  }

  function handleDragEnd(e) {
    if (isCloserToRightEdge(e)) {
      updateToggle(true);
    } else {
      updateToggle(false);
    }
  }
}

With this approach, both the Toggle component and its parent component update their state during the event. React batches updates from different components together, so there will only be one render pass.

✅ Even Better: Lift state up (fully controlled component)

// ✅ Also good: the component is fully controlled by its parent
function Toggle({ isOn, onChange }) {
  function handleClick() {
    onChange(!isOn);
  }

  function handleDragEnd(e) {
    if (isCloserToRightEdge(e)) {
      onChange(true);
    } else {
      onChange(false);
    }
  }
}

"Lifting state up" lets the parent component fully control the Toggle by toggling the parent's own state.

10. Passing Data to the Parent

❌ Bad: Fetching in child and passing to parent

function Parent() {
  const [data, setData] = useState(null);
  // ...
  return <Child onFetched={setData} />;
}

function Child({ onFetched }) {
  const data = useSomeAPI();

  // 🔴 Avoid: Passing data to the parent in an Effect
  useEffect(() => {
    if (data) {
      onFetched(data);
    }
  }, [onFetched, data]);
}

Problem: In React, data flows from the parent components to their children. When you see something wrong on the screen, you can trace where the information comes from by going up the component chain.

✅ Good: Fetch in parent and pass down

function Parent() {
  const data = useSomeAPI();
  // ...
  // ✅ Good: Passing data down to the child
  return <Child data={data} />;
}

function Child({ data }) {
  // ...
}

This is simpler and keeps the data flow predictable: the data flows down from the parent to the child.

When You DO Need Effects

1. Subscribing to External Stores

⚠️ Manual subscription (not ideal)

function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(true);

  useEffect(() => {
    function updateState() {
      setIsOnline(navigator.onLine);
    }

    updateState();

    window.addEventListener('online', updateState);
    window.addEventListener('offline', updateState);

    return () => {
      window.removeEventListener('online', updateState);
      window.removeEventListener('offline', updateState);
    };
  }, []);

  return isOnline;
}

✅ Better: Use useSyncExternalStore

function subscribe(callback) {
  window.addEventListener('online', callback);
  window.addEventListener('offline', callback);
  return () => {
    window.removeEventListener('online', callback);
    window.removeEventListener('offline', callback);
  };
}

function useOnlineStatus() {
  // ✅ Good: Subscribing to an external store with a built-in Hook
  return useSyncExternalStore(
    subscribe, // React won't resubscribe for as long as you pass the same function
    () => navigator.onLine, // How to get the value on the client
    () => true // How to get the value on the server
  );
}

This approach is less error-prone than manually syncing mutable data to React state with an Effect.

2. Fetching Data

✅ Fetching in Effect (with proper cleanup)

function SearchResults({ query }) {
  const [results, setResults] = useState([]);
  const [page, setPage] = useState(1);

  useEffect(() => {
    let ignore = false;

    fetchResults(query, page).then(json => {
      if (!ignore) {
        setResults(json);
      }
    });

    return () => {
      ignore = true; // ✅ Cleanup function to ignore stale responses
    };
  }, [query, page]);

  function handleNextPageClick() {
    setPage(page + 1);
  }
}

Why this is appropriate:

You want to keep results synchronized with the current query and page
The fetch happens because the component was displayed, not because of a specific interaction

Important: The cleanup function with ignore flag prevents race conditions when typing fast.

✅ Even Better: Use a framework or custom hook

function SearchResults({ query }) {
  const [page, setPage] = useState(1);
  const params = new URLSearchParams({ query, page });

  // ✅ Modern frameworks provide more efficient built-in data fetching
  const results = useData(`/api/search?${params}`);

  function handleNextPageClick() {
    setPage(page + 1);
  }
}

Modern frameworks provide more efficient built-in data fetching mechanisms that handle:

Caching responses
Avoiding network waterfalls
Prefetching data
Server-side rendering

Key Takeaways

Decision Tree: Effect vs Event Handler

Ask yourself: What kind of logic is this from the user's perspective?

Caused by a particular interaction → Event Handler
Caused by the user seeing the component → Effect

State Behaves Like a Snapshot

function handleClick() {
  setRound(round + 1); // round is still the old value here

  // If you need the next value:
  const nextRound = round + 1;
  // Use nextRound for calculations
}

Inside event handlers, state reflects the value at the time the user clicked.

Benefits of Avoiding Unnecessary Effects

Faster - Avoids extra render passes and cascading updates
Simpler - Less code, easier to understand data flow
Less error-prone - Avoids bugs from synchronization issues
More maintainable - Easier to modify and extend

When Effects ARE Appropriate

Synchronizing with external systems (browser APIs, third-party libraries, network)
Data fetching (with proper cleanup for race conditions)
Subscribing to external stores (prefer useSyncExternalStore)

Common Patterns Summary

Scenario	❌ Don't Use Effect	✅ Use Instead
Transform data	Effect + setState	Calculate during render
Cache expensive calc	Effect + setState	`useMemo`
Reset all state	Effect on prop change	`key` prop
Adjust some state	Effect on prop change	Calculate during render
Share event logic	Effect	Extracted function
POST on user action	Effect	Event handler
POST on page view	Event handler	Effect
Chain of updates	Multiple Effects	Single event handler
App initialization	Effect	Top-level code
Notify parent	Effect calling onChange	Call in event handler
Pass data to parent	Effect	Lift state up
Subscribe to store	Manual Effect	`useSyncExternalStore`
Fetch data	Manual Effect	Framework/custom hook

Remember: Effects are a powerful feature, but they're also an escape hatch. Use them when you need to synchronize with systems outside of React, not for orchestrating your application's data flow.

How We Migrated 150+ Components from MUI to Carbon Design System v11 (And Reduced Accessibility Violations by 78%)

Thoithoi Shougrakpam — Mon, 30 Mar 2026 17:23:04 +0000

A practical account of a large-scale UI library migration — what we planned, what broke, and what we'd do differently.

When our team decided to migrate from Material UI to Carbon Design System v11, the scope was clear: 150+ components across an enterprise DNS platform, hundreds of thousands of lines of React code, and zero tolerance for regressions on production traffic.

What wasn't clear was how much the migration would teach us about the hidden cost of design system debt.

Here's what we learned.

Why We Left MUI

MUI is excellent. We're not here to trash it. But for a product shipping inside IBM's ecosystem, we were maintaining two parallel design languages — MUI's Material-influenced components and IBM's Carbon — in ways that created real friction:

Accessibility inconsistencies: MUI and Carbon have different ARIA patterns. Running them side-by-side meant our a11y audit results were impossible to reason about systematically.
Token misalignment: MUI's theming system uses its own token schema. Syncing it with Carbon's design tokens required manual overrides that drifted every major version.
Duplication: We had parallel implementations of the same UI patterns (modals, data tables, notifications) in both systems because some features were built before Carbon was standardized internally.

The business case was straightforward: standardize on one system, reduce the a11y violation count, and cut the long-term maintenance surface area.

What the Migration Actually Looked Like

Phase 1: Audit Before You Touch Anything

Before writing a single line of migration code, we did a full component inventory. Every MUI import, tagged by:

Component type (Button, Modal, DataTable, etc.)
Usage frequency across the codebase
Complexity (prop surface area, custom styling overrides)
WCAG failure count from our latest audit

This gave us a priority-ordered migration queue. We started with high-frequency, low-complexity components (buttons, form elements, notifications) and saved the complex ones (data tables, modals with deeply custom behavior) for last.

Lesson: Don't migrate in file order. Migrate in impact order. Fixing <Button> across 30 files in one PR is fast and momentum-building. Fixing a deeply customized <DataTable> is a sprint's worth of work.

Phase 2: Coexistence, Not Big Bang

We explicitly rejected a big-bang cutover. The goal was a migration where both systems could live together during the transition, which meant:

No shared global styles between MUI and Carbon — we kept them scoped.
A migration tracking doc that listed every component, its status (MUI / In Progress / Carbon), and the engineer assigned to it.
Incremental PRs by page/feature area, not by component type — this kept feature work reviewable and deployable without blocking the whole migration.

The coexistence period lasted about three months. It wasn't elegant, but it worked.

Phase 3: Accessibility as a Migration Test

Here's where things got interesting.

Because Carbon is built with WCAG 2.1 AA compliance as a first-class constraint, migrating to Carbon components was — by construction — also an accessibility remediation pass. We set up automated a11y scanning (using axe-core in our Cypress suite) to run on every PR during the migration.

This gave us something useful: a per-PR accessibility delta. Each Carbon migration PR came with a number: how many violations were added or removed. Teams could see the a11y impact of their work in CI.

By the end of the migration, we had reduced our total WCAG violation count by 78%.

That number sounds impressive — and it is — but it's also a measure of how much debt had accumulated under our previous approach. The violations didn't appear overnight. They accumulated slowly, component by component, over years of building with a system that wasn't designed for our a11y requirements from the ground up.

What Broke (And How We Fixed It)

1. Theme Token Mismatches

Carbon v11 introduces a new token structure (using CSS custom properties instead of Sass variables). If you have any legacy Sass-based theming, this is a full rewrite, not a find-and-replace.

What we did: Audited every Sass file for hardcoded hex values or MUI theme variable references. Replaced them with Carbon's $layer-01, $text-primary, etc. tokens. This took longer than expected — hardcoded colors are invisible until you're looking for them.

2. Modal and Focus Trap Behavior

MUI's <Modal> and Carbon's <Modal> handle focus trapping differently. We had several flows where keyboard navigation broke silently — no visible error, just focus escaping to the wrong element.

What we did: Added keyboard navigation Cypress tests for every modal flow before migrating it. If a test passed on MUI and failed on Carbon, we knew exactly what to fix. If we hadn't instrumented this first, we'd have shipped broken focus behavior to users.

3. DataTable Complexity

Carbon's <DataTable> is a compound component with a very different API from MUI's <DataGrid>. We had 30+ table instances, many with custom sorting, filtering, and batch action logic baked in.

What we did: Built a single abstraction layer (<DnsDataTable>) that wrapped Carbon's DataTable and exposed only the props our platform actually needed. This gave us one migration target instead of 30, and it's been easier to maintain since.

4. Icon Library Differences

MUI uses @mui/icons-material. Carbon uses @carbon/icons-react. Not one-to-one. Some icons have no Carbon equivalent; some Carbon icons have different semantic names.

What we did: Created an icon mapping spreadsheet during the audit phase. For icons with no equivalent, we either used a close Carbon alternative or imported the SVG directly.

What We'd Do Differently

Start the a11y scanning earlier. We added automated a11y tests mid-migration. If we'd set them up before we started, we'd have had a cleaner baseline and caught more regressions in early PRs.

Automate the import codemod. For simple component swaps (e.g., import { Button } from '@mui/material' → import { Button } from '@carbon/react'), a codemod would have saved significant time. We wrote a few but not systematically enough.

Treat the migration as a product feature, not a background task. The teams that moved fastest were the ones that dedicated sprint capacity explicitly to migration work. The teams that tried to do it "alongside" feature work consistently took 2x longer.

Results

After the migration was complete:

78% reduction in WCAG accessibility violations
150+ components migrated to Carbon v11
Design consistency across the platform — no more hybrid MUI/Carbon UIs
Reduced long-term maintenance surface — one design system to track for updates, security patches, and React compatibility

The migration also surfaced a pattern we hadn't anticipated: Carbon's enforced structure pushed us toward better component composition habits. When you can't just pile custom styles on top of an MUI component, you're forced to think more carefully about what your component actually needs to expose.

That's a side effect we'd take again.

Takeaways

If you're considering a similar migration:

Audit before you migrate. Know your component inventory, complexity, and a11y debt before writing the first line.
Coexistence over big bang. Ship incrementally. A broken design system migration kills trust faster than almost any other engineering failure.
Use a11y scanning as your migration test suite. If you're moving to a more accessible system, instrument that signal from day one.
Build abstraction layers for complex components. One internal DataTable wrapper is infinitely easier to migrate than 30 individual instances.
Allocate sprint capacity. Migrations that happen "on the side" don't happen.

_Have questions about the migration approach or Carbon v11 specifics? Drop them in the comments — happy to go deeper on any section.

WCAG 2.2: What Changed, Why It Matters, and How to Implement It

Thoithoi Shougrakpam — Mon, 30 Mar 2026 17:19:49 +0000

Nine new success criteria. One removed. Here is what every frontend engineer needs to know.

WCAG 2.2 became an official W3C Recommendation on December 12, 2024. If your team is still targeting 2.1 as a compliance baseline, you are already behind. The W3C explicitly advises using 2.2 to maximize future applicability of accessibility efforts, and regulators in the EU, UK, and US are actively aligning their policies to the latest version.

This article covers every new success criterion using a consistent format: what the spec requires, why the criterion exists and who it protects, and how to implement it in practice.

What Was Removed First: 4.1.1 Parsing

Before the new criteria, one was cut. WCAG 2.2 removed 4.1.1 Parsing, which previously required well-formed HTML so assistive technologies could reliably parse it.

Why removed: Modern browsers and screen readers have become resilient enough to handle malformed markup without accessibility failures. The criterion no longer reliably predicted real-world accessibility outcomes, so the working group dropped it.

Practical note: If your organization is contractually obligated to WCAG 2.0 or 2.1 conformance, you may still need to test and report on 4.1.1 separately. For new 2.2 audits, it is gone.

The 9 New Success Criteria

1. Focus Not Obscured (Minimum) -- 2.4.11 -- Level AA

What: When a UI component receives keyboard focus, the focused element must not be entirely hidden by author-created content. Partially obscured is acceptable at this level. Entirely hidden is not.

Why: Users who navigate by keyboard (people with motor disabilities, switch device users, power users) need to see where focus is at all times. Sticky headers, floating cookie banners, fixed chat widgets, and bottom navigation bars are the most common offenders. When focus moves behind one of these layers and disappears completely, the user loses their place on the page with no visual cue for what is currently selected. This is especially disorienting for users with cognitive disabilities who are more sensitive to context loss during a task.

How to implement:

The core fix is ensuring scroll-padding-top accounts for any fixed header height so the browser scrolls enough to keep focused elements visible.

/* If your sticky header is 64px tall */
html {
  scroll-padding-top: 80px; /* header height + breathing room */
}

/* Alternatively, scoped to focusable elements */
a:focus,
button:focus,
[tabindex]:focus {
  scroll-margin-top: 80px;
}

For dynamic header heights (collapsing navs, announcement banners that appear after load), update the value from JavaScript:

function updateScrollPadding() {
  const header = document.querySelector('.sticky-header');
  const height = header?.getBoundingClientRect().height ?? 0;
  document.documentElement.style.scrollPaddingTop = `${height + 16}px`;
}

window.addEventListener('resize', updateScrollPadding);
updateScrollPadding();

Test it: Tab through your page with a sticky header visible. Every focused element should be at least partially visible above the fold.

2. Focus Not Obscured (Enhanced) -- 2.4.12 -- Level AAA

What: Same intent as 2.4.11, but stricter. The focused component must not be obscured at all, not even partially.

Why: At AA (2.4.11), a focused element that is 10% visible technically passes. For users with low vision who rely on high zoom levels or screen magnification, even partial obscuring can make the focus indicator undetectable in practice. The AAA version closes that gap entirely.

How to implement:

Everything from 2.4.11 applies. The additional requirement is that no part of the focused element is covered by overlapping author-created content. In practice this means:

scroll-padding values must fully clear the focused element above any sticky layers.
Fixed overlays (modals, drawers, sheets) must trap focus inside themselves while open, so keyboard focus can never land on content behind them.

// Trap focus inside an open modal
function trapFocus(modalElement) {
  const focusable = modalElement.querySelectorAll(
    'a, button, input, textarea, select, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];

  modalElement.addEventListener('keydown', (e) => {
    if (e.key !== 'Tab') return;
    if (e.shiftKey) {
      if (document.activeElement === first) {
        e.preventDefault();
        last.focus();
      }
    } else {
      if (document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    }
  });
}

3. Focus Appearance -- 2.4.13 -- Level AAA

What: When a keyboard focus indicator is visible, it must meet specific size and contrast requirements. The focus indicator area must be at least the perimeter of the unfocused component multiplied by 2 CSS pixels. The contrast ratio between focused and unfocused states must be at least 3:1 against adjacent colors.

Why: Browser default focus outlines are frequently invisible against common backgrounds, and many codebases globally suppress them with outline: none (still a widespread anti-pattern). Users with low vision, cognitive disabilities, and anyone relying entirely on keyboard navigation depend on a focus indicator that is visually obvious, not just technically present. A faint, thin blue ring at low contrast does not serve these users.

How to implement:

The first step is removing the global outline: none pattern. If you need to suppress the browser ring for mouse users, use :focus-visible instead of :focus:

/* Wrong: removes focus ring for everyone, including keyboard users */
*:focus {
  outline: none;
}

/* Right: removes ring only when pointer (not keyboard) is in use */
*:focus:not(:focus-visible) {
  outline: none;
}

/* Custom focus indicator that satisfies AAA geometric and contrast requirements */
*:focus-visible {
  outline: 3px solid #0f62fe;
  outline-offset: 2px;
  border-radius: 2px;
}

A practical shortcut: a 3px solid outline in a color with at least 3:1 contrast against the surrounding background satisfies the geometric requirement for most standard interactive components. For components on dark surfaces, check the contrast of your focus color against the dark background, not just the default page background.

4. Dragging Movements -- 2.5.7 -- Level AA

What: Any functionality that uses a dragging movement (click-and-drag, touch drag) must also be achievable with a single pointer action (click or tap) without dragging. Exceptions apply only when the drag is essential to the functionality itself.

Why: Dragging requires simultaneously pressing, holding, and moving a pointer. This compound gesture is unreliable or impossible for users with hand tremors, limited fine motor control, or motor disabilities affecting pointer precision. Sortable lists, kanban boards, sliders, map pan gestures, and date range pickers are common failure cases. The criterion does not prohibit drag interactions. It requires that a non-drag path exists to accomplish the same result.

How to implement:

For sortable lists, provide explicit move buttons alongside the drag handle:

function SortableItem({ item, onMoveUp, onMoveDown }) {
  return (
    <div draggable onDragStart={...} onDragEnd={...}>
      <span>{item.label}</span>
      <button aria-label={`Move ${item.label} up`} onClick={onMoveUp}>↑</button>
      <button aria-label={`Move ${item.label} down`} onClick={onMoveDown}>↓</button>
    </div>
  );
}

For range sliders, use native <input type="range"> wherever possible. It supports arrow key adjustment out of the box. Custom slider implementations frequently break keyboard support:

<input
  type="range"
  min={0}
  max={100}
  value={value}
  onChange={(e) => setValue(Number(e.target.value))}
  aria-label="Price range maximum"
/>

For map or canvas drag interactions, provide explicit pan controls: arrow-key panning and clickable pan buttons in the UI.

5. Target Size (Minimum) -- 2.5.8 -- Level AA

What: The size of the pointer target for interactive elements must be at least 24x24 CSS pixels. Exceptions apply when: the target's offset from adjacent targets is at least 24px, the target is inline within text content, the browser controls the target size (default form controls), or a small size is essential to the information conveyed.

Why: Small tap targets fail users with tremors, limited dexterity, or motor disabilities who use alternative pointer devices with reduced precision. Tightly packed icon buttons, small checkboxes, link-dense navigation menus, and close buttons in notification toasts are the most common failure patterns. Note that 24x24px is the AA minimum. The AAA version (2.5.5, carried forward from 2.1) requires 44x44px. Most mobile UX guidelines already recommend 44px. WCAG 2.2 establishes the legal floor.

How to implement:

Set a baseline minimum for all interactive elements:

button,
a,
[role="button"],
input[type="checkbox"],
input[type="radio"] {
  min-width: 24px;
  min-height: 24px;
}

/* Prefer the AAA-level 44x44 on touch interfaces */
@media (pointer: coarse) {
  button,
  a,
  [role="button"] {
    min-width: 44px;
    min-height: 44px;
  }
}

For icon-only buttons where the visual size is constrained by design, expand the hit area using padding while keeping the visible footprint the same:

.icon-button {
  padding: 10px; /* expands hit area to 44x44 if icon is 24x24 */
  display: inline-flex;
  align-items: center;
  justify-content: center;
}

The spacing exception is a legitimate tool for constrained layouts. If two 16x16 icons are spaced so their center-to-center distance is 24px or more, they satisfy the minimum even without being 24x24 in physical size. Use it as a fallback, not a design default.

6. Consistent Help -- 3.2.6 -- Level A

What: If a web page provides a help mechanism (human contact, self-help documentation, automated contact, or a contact form), that mechanism must appear in the same relative location across all pages within the site.

Why: Users with cognitive disabilities often need help completing tasks and struggle when support resources appear in different places on different pages. If the help icon is in the top-right corner on the homepage but shifts to the footer on the checkout page, the inconsistency creates friction precisely when the user is most likely to need assistance. This criterion does not require that you have a help mechanism. It only requires that if you do, its location is stable.

How to implement:

This is primarily a layout and design system decision. Anchor help mechanisms inside a shared layout component so they cannot drift between pages:

// Layout.jsx
export function Layout({ children }) {
  return (
    <>
      <GlobalHeader />     {/* help trigger lives here, always */}
      <main>{children}</main>
      <GlobalFooter />
    </>
  );
}

Avoid conditionally hiding the help trigger on specific page types. If suppression is unavoidable (full-screen checkout flows, immersive experiences), make sure the mechanism reappears in the same location once normal layout resumes.

"Same relative location" means the same area of the page (top-right, bottom-right, etc.), not exact pixel coordinates. Responsive layouts that shift the help button between breakpoints are acceptable as long as it is consistently placed within each breakpoint's layout pattern.

7. Redundant Entry -- 3.3.7 -- Level A

What: Information that a user has already provided in a multi-step process must either be auto-populated in subsequent steps or be selectable from previously entered values. Users must not be required to re-enter the same information within the same session unless re-entry is essential (e.g., password confirmation for security) or the information is no longer valid.

Why: Re-entering data is a significant cognitive and motor burden. For users with cognitive disabilities, being asked to retype a name or address they entered three steps ago interrupts task flow, increases error likelihood, and often causes abandonment. For users with motor disabilities, every additional keystroke carries a real physical cost. This criterion formalizes what good UX already recommends: do not ask for something you already have.

How to implement:

In a multi-step React form, store session state at a high level and pre-populate later steps:

// FormContext.jsx
const FormContext = React.createContext({});

export function FormProvider({ children }) {
  const [formData, setFormData] = React.useState({});

  const updateFormData = (values) => {
    setFormData((prev) => ({ ...prev, ...values }));
  };

  return (
    <FormContext.Provider value={{ formData, updateFormData }}>
      {children}
    </FormContext.Provider>
  );
}

// Step 3: Shipping -- pre-populate from billing when same
function ShippingStep() {
  const { formData, updateFormData } = React.useContext(FormContext);
  const [sameAsBilling, setSameAsBilling] = React.useState(false);

  const address = sameAsBilling
    ? formData.billingAddress
    : formData.shippingAddress;

  return (
    <>
      <label>
        <input
          type="checkbox"
          checked={sameAsBilling}
          onChange={(e) => setSameAsBilling(e.target.checked)}
        />
        Same as billing address
      </label>
      <AddressFields defaultValues={address} onChange={...} />
    </>
  );
}

The "same as billing" pattern already present in most e-commerce checkouts is a textbook 3.3.7 implementation. Apply the same logic to any multi-step flow where information asked in step N could have been collected in step N-1 or earlier.

8. Accessible Authentication (Minimum) -- 3.3.8 -- Level AA

What: A cognitive function test (memorizing a password, solving a puzzle, transcribing characters) must not be required at any step of an authentication process unless: an alternative authentication method is available that does not require a cognitive function test, a mechanism is available to help complete the test (such as copy-paste support or a password manager), or the test involves recognizing objects or personal content the user themselves provided.

Why: Password recall is itself a cognitive function test. Many users with cognitive disabilities, memory impairments, or learning disabilities cannot reliably memorize and recall complex passwords on demand. CAPTCHAs add another cognitive or visual puzzle on top of that. This criterion protects access to the authentication layer itself, which is a prerequisite for using everything else on the platform.

How to implement:

The highest-impact single change: allow paste into password fields and respect autocomplete attributes. Blocking paste breaks password managers and forces manual re-entry.

// Wrong: blocks paste, breaks password managers
<input
  type="password"
  onPaste={(e) => e.preventDefault()}
/>

// Right: paste allowed, autocomplete declared
<input
  type="password"
  autoComplete="current-password"
/>

Use the correct autocomplete values for the browser and password managers to fill credentials automatically:

<input type="email" autocomplete="username" />
<input type="password" autocomplete="current-password" />
<input type="password" autocomplete="new-password" /> <!-- registration -->

Additional paths to compliance:

Offer magic link login (no password to recall).
Support passkeys as an alternative.
If you use a CAPTCHA, provide an audio alternative and a non-CAPTCHA path for users who cannot complete visual challenges.

The object recognition exception covers CAPTCHAs that ask users to identify images they uploaded themselves (security images, personal photos). These are permitted because the cognitive anchor is personal memory, not abstract recall.

9. Accessible Authentication (Enhanced) -- 3.3.9 -- Level AAA

What: Same as 3.3.8, but removes the object recognition and personal content exceptions. No cognitive function test of any kind is permitted anywhere in the authentication flow.

Why: Even object recognition and personal image selection require a level of memory and visual processing that users with severe cognitive or visual disabilities may not be able to reliably perform. The AAA version is an absolute requirement: authentication cannot depend on cognitive tests at all.

How to implement:

The only conformant paths at AAA are authentication methods that require no cognitive recall:

Passkeys (WebAuthn/FIDO2): device-level biometric or PIN-based auth. No password to memorize or recall.

// Passkey authentication
const assertion = await navigator.credentials.get({
  publicKey: {
    challenge: serverGeneratedChallenge,
    allowCredentials: [{ type: 'public-key', id: existingCredentialId }],
    userVerification: 'preferred',
  },
});
// Send assertion to server for verification

Magic links: one-time login URLs delivered to a verified email or phone. The user clicks a link in their inbox. No password involved.

SSO delegation: the authentication burden is delegated to a trusted identity provider. The provider's own authentication is outside your conformance boundary.

AAA is not required for most products, but passkeys are rapidly becoming the industry default regardless of compliance requirements. Implementing them satisfies the accessibility requirement and the general trend toward passwordless authentication simultaneously.

Audit Checklist for WCAG 2.2 Compliance

If you are auditing an existing product, prioritize in this order:

Level A (minimum baseline)

[ ] Help mechanisms appear in a consistent location across all pages (3.2.6)
[ ] Multi-step forms do not re-ask for information already collected in the session (3.3.7)

Level AA (legal and enterprise standard)

[ ] No focused element is entirely hidden by sticky headers, footers, or overlays (2.4.11)
[ ] All interactive targets are at least 24x24 CSS pixels or have adequate spacing (2.5.8)
[ ] Every drag interaction has a single-pointer alternative (2.5.7)
[ ] Password fields allow paste and declare correct autocomplete attributes (3.3.8)
[ ] No authentication step requires a cognitive function test without an accessible alternative (3.3.8)

Level AAA (aspirational or contractual)

[ ] No focused element is partially obscured by author-created overlays (2.4.12)
[ ] Focus indicators meet minimum size and 3:1 contrast requirements (2.4.13)
[ ] Authentication requires no cognitive function tests of any kind (3.3.9)

The Bigger Picture

WCAG 2.2's additions are tightly scoped around three user groups: people with cognitive or learning disabilities, users with low vision, and users on mobile and touch devices. Every new criterion maps to a failure mode that real products ship regularly: password fields that block paste, drag interactions with no keyboard fallback, sticky headers that swallow focused elements, icon buttons too small to tap precisely.

None of these fixes are expensive once you know what to look for. The authentication changes are often one autocomplete attribute away. The target size and focus visibility issues are a few lines of CSS. The redundant entry problem is a state management question you have probably already partially solved elsewhere in your codebase.

The investment is low. The user impact is not.

Questions about implementing any of these criteria? Drop them in the comments.