DEV Community: Srikar Phani Kumar Marti

Design Systems and Accessibility: Mechanisms to Enforce Consistent Focus Management

Srikar Phani Kumar Marti — Mon, 05 Oct 2026 11:01:19 +0000

Ever been puzzled when tabbing through a complex UI built from a design system, only to have the focus jump in unexpected ways or disappear entirely? Maybe a modal’s close button isn’t reachable by keyboard, or focus lands on something visually hidden. It’s a tiny annoyance for some, but a showstopper for keyboard users and screen reader folks.

I’ve faced this exact headache while working on a large React design system. The components promised accessibility out of the box, but subtle app-level overrides or custom wrappers sometimes broke the focus flow. Tracking down where the focus management logic lived, and why it wasn’t working, led me down a rabbit hole of internal mechanisms that design systems use to enforce consistent, accessible focus.

Let me share what I learned about how design systems coordinate focus, how they integrate with ARIA, and how you can debug when your app’s overrides clash with those defaults.

Focus management is more than tabindex

Setting tabindex is the classic way to control keyboard focus order. But design systems go way beyond sprinkling tabindex attributes.

For example, take a dropdown component. When you open it, focus should move into the dropdown’s first interactive item. When you close it, focus needs to return to the button that triggered it. And keyboard navigation inside the dropdown needs to cycle logically.

Design systems bake these rules into their components using JavaScript focus management. They listen for keyboard events, programmatically call .focus() on appropriate elements, and maintain internal state about what should be focused next.

This means a lot of logic lives inside the system’s components, not just in markup.

How design systems enforce consistent focus

1. Centralized focus utilities

Many systems include shared focus utilities: helper functions or hooks that set focus, trap focus within dialogs, or restore focus after navigation. These utilities handle quirks across browsers and assistive tech.

For example, a "focus trap" utility listens for tab key presses and ensures focus cycles only within a modal’s interactive elements, preventing keyboard users from tabbing to elements behind the modal.

2. Focus context and state

Some systems create a focus context that tracks the current focus target and allows nested components to coordinate. For example, a tab panel component and its tabs share focus state so that activating a tab moves focus correctly and updates the panel.

3. ARIA integration

ARIA attributes are part of the story but not the whole story. Design systems use ARIA roles like role="dialog", aria-modal="true", and aria-labelledby to help screen readers understand component purpose and relationships.

But focus management is still done with JavaScript. For instance, an accessible modal will set aria-hidden="true" on background content and shift focus to the modal container when opened.

4. Keyboard event handling

Design systems intercept keyboard events like Tab, Shift+Tab, Escape, and arrow keys to customize focus movement and component behavior.

For example, arrow keys might move focus between menu items, Escape closes a modal and returns focus, and Tab cycles focus inside a focus trap.

When your app overrides break focus management

I ran into bugs when app-level styles or wrappers overrode the design system’s components. Here are common pitfalls:

Custom wrappers missing focus forwarding: If you wrap a focusable component but don’t forward refs properly, programmatic .focus() calls inside the system fail silently.
CSS hiding focus indicators: Overriding focus styles with outline: none or other rules can make focus invisible.
Conflicting event handlers: Adding keyboard handlers that prevent default behavior or stop propagation can break the system’s internal focus logic.
Dynamic rendering mismatches: Rendering components conditionally without coordinating focus restoration leads to lost focus or unexpected jumps.

Debugging focus issues in design systems

Use browser devtools’ accessibility inspectors

Browsers like Chrome and Firefox have accessibility panes showing the accessibility tree and focusable elements. Use these to verify which elements are focusable and whether ARIA attributes are set correctly.

Manual focus inspection

Try tabbing through your app step by step. Note where focus lands, where it disappears, or where it loops unexpectedly.

Use document.activeElement in the console to see the current focused element at any point.

Check event listeners

Inspect the event listeners on elements to see if keyboard events are handled or blocked.

Verify ref forwarding

If your components use React, ensure ref forwarding is correctly set up so the design system can call .focus() on the right DOM node.

Test with screen readers

Keyboard focus and visual focus indicators are only part of accessibility. Test with screen readers like NVDA or VoiceOver to make sure focus changes align with announcements.

Example: Focus trap in a modal

Here’s a simplified example of how a focus trap works inside a modal component:

function Modal({isOpen, onClose, children}) {
  const modalRef = useRef(null);

  useEffect(() => {
    if (!isOpen) return;

    const focusableElements = modalRef.current.querySelectorAll(
      'a[href], button, input, textarea, select, [tabindex]:not([tabindex="-1"])'
    );
    const firstElement = focusableElements[0];
    const lastElement = focusableElements[focusableElements.length - 1];

    function handleKeyDown(e) {
      if (e.key === 'Tab') {
        if (e.shiftKey) {
          if (document.activeElement === firstElement) {
            e.preventDefault();
            lastElement.focus();
          }
        } else {
          if (document.activeElement === lastElement) {
            e.preventDefault();
            firstElement.focus();
          }
        }
      }

      if (e.key === 'Escape') {
        onClose();
      }
    }

    modalRef.current.addEventListener('keydown', handleKeyDown);
    firstElement.focus();

    return () => {
      modalRef.current.removeEventListener('keydown', handleKeyDown);
    };
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    <div role="dialog" aria-modal="true" ref={modalRef}>
      {children}
    </div>
  );
}

This snippet traps focus inside the modal while it’s open and closes on Escape. Design systems build on this idea but handle edge cases and browser quirks.

Wrapping up

Focus management inside design systems is a mix of ARIA, JavaScript, event handling, and CSS working together. It’s not enough to add tabindex and call it done.

If you build or maintain a design system, consider:

Providing standardized focus utilities
Documenting expected focus behavior for each component
Testing with keyboard and screen readers
Encouraging app teams to respect focus management and avoid harmful overrides

If you’re integrating a design system and hit focus bugs, dig into the event handling, ref forwarding, and CSS focus styles. Use browser devtools and assistive tech to observe what’s happening.

These mechanisms might feel like plumbing, but getting focus right makes your UI genuinely usable for everyone.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

Understanding React’s useTransition: Mechanisms and Performance Implications

Srikar Phani Kumar Marti — Wed, 30 Sep 2026 13:18:40 +0000

Ever had a React app where an update causes a janky UI or a spinner that pops up out of nowhere , but only sometimes? I ran into this recently when trying to make a search input feel smooth while fetching results. I used useTransition to defer the heavy update, but I didn’t fully grasp what React was doing behind the scenes.

Turns out, useTransition is not just a fancy hook to slap on some state. It’s a clever way React’s concurrent rendering lets you mark updates as "non-urgent." That impacts scheduling, priority, and how your UI feels to users.

Let me walk you through what really happens under the hood with useTransition, how it interacts with React’s scheduler, and when it actually helps your app’s performance.

The developer moment: Why did my spinner randomly appear?

I had a component with a search box. Typing updated a local state immediately (the input’s value), but then I also kicked off a data fetch and updated the results state. The results update triggered a big list render, which sometimes made typing laggy.

I wrapped the results state update in a startTransition callback from useTransition:

const [isPending, startTransition] = useTransition();
const [query, setQuery] = useState('');
const [results, setResults] = useState([]);

function onChange(e) {
  setQuery(e.target.value); // urgent update, keep input responsive
  startTransition(() => {
    fetchResults(e.target.value).then(setResults); // deferred update
  });
}

Now React shows a spinner when isPending is true, which means the transition is in flight. But the spinner sometimes flashes for just a split second or not at all. Why?

The answer lies in how React prioritizes these updates and schedules rendering work.

useTransition under the hood: marking updates as low priority

React’s concurrent mode lets your app interrupt rendering work to keep the UI responsive. Priorities matter. User input is high priority. Visual updates that could wait? Lower priority.

useTransition leverages this by tagging state updates inside startTransition as "transitions": low priority work.

When you call startTransition(() => setState(newValue)), React:

Marks that update as non-urgent.
Schedules it with a lower priority than input or animation updates.
Allows React to keep rendering high priority work first (like updating the input value).

This means your input feels snappy even if the results list takes time to render or fetch.

What happens in React’s scheduler?

React’s scheduler manages a queue of updates with priorities:

High priority: user input, clicks, focus
Transition priority: updates inside startTransition
Normal priority: other updates

Imagine React like a cook in a busy kitchen. Urgent orders (user input) get served immediately. Less urgent ones (transitions) wait for a free moment.

When a transition update is scheduled, React tries to render it in chunks, yielding control back to the browser if there’s more urgent work.

If the user keeps typing fast, React can pause rendering the transition and show the latest input first.

This is why your spinner may flash briefly:

If the transition finishes very fast, React commits it immediately, so isPending toggles quickly.
If the user interrupts by typing more, React may drop the previous transition and start a new one, causing flickers.

The `isPending` flag: what you’re really tracking

useTransition gives you isPending, a boolean that indicates if there’s any transition update still "in progress."

But "in progress" here means "React hasn’t committed the transition update to the DOM yet."

It doesn’t mean your fetch is still pending (you have to track that yourself). It means React’s rendering of the update is ongoing or waiting.

Because React batches and may interrupt work, isPending can toggle quickly, making spinners flash unexpectedly.

When to use useTransition , and when not to

useTransition shines when you want to:

Keep input or UI responsiveness snappy by deferring heavy updates
Show some feedback (like a spinner) while transition updates are rendering
Avoid blocking urgent updates with less urgent ones

But it’s not a silver bullet:

If your deferred update is tiny or fast, the spinner can feel like flicker. You might prefer to skip it.
If you don’t handle loading states well, users might get confused.
If you’re not in concurrent mode or React 18+, useTransition won’t do much.

A concrete example: search input with and without useTransition

Imagine a big list that takes 300ms to render.

Without useTransition:

User types a letter
React updates query and results immediately
UI blocks for 300ms, input lags or freezes

With useTransition:

User types a letter
React updates query immediately (urgent)
React schedules results update as a transition
Input stays responsive
Spinner shows while results render

But if the user types multiple letters quickly, React might skip rendering intermediate results, showing only the latest. The spinner might flash briefly or never appear if rendering is too fast.

Debugging tip: React DevTools Profiler and `isPending`

React DevTools Profiler can show you when transitions start and end. You’ll see how React schedules and prioritizes updates.

When debugging flickering spinners or janky UI, check:

Are you using startTransition correctly?
Is your deferred update actually expensive?
How often does isPending toggle?

You can also throttle your CPU or network to simulate slow rendering and fetches, making the transition more visible.

What happens if you nest transitions or mix priorities?

React lets you nest transitions, but inside a transition, a state update is always low priority unless you explicitly mark it urgent.

Mixing urgent and transition updates can lead to surprising UI behaviors if not managed carefully.

For example, if you update input state inside a transition, input responsiveness suffers. Always update urgent UI state outside startTransition.

Wrapping up

useTransition is a subtle but powerful tool to tell React, "This update can wait a bit." It works by marking state updates as low priority, letting React’s concurrent scheduler keep your UI responsive.

Understanding the scheduler, priorities, and what isPending really means helps you use useTransition effectively and avoid flickery spinners or janky typing.

Next time your React UI feels sluggish or your loading spinners flash unpredictably, remember what’s happening under the hood with transitions , it’s a conversation between your code and React’s scheduler to keep things smooth.

Give it a try in your app, measure with React DevTools, and tweak your priorities to find the sweet spot between responsiveness and smooth updates.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

Design Systems and Focus Management: Mechanisms to Avoid Focus Loss and Trap Bugs

Srikar Phani Kumar Marti — Fri, 25 Sep 2026 13:48:04 +0000

Ever had that moment where you open a modal or dropdown, start tabbing through, and suddenly the keyboard focus vanishes into thin air? Or worse, you get stuck inside a widget with no way out without a mouse?

I’ve been there, frustrated and scratching my head, especially when these bugs crop up in polished design systems you’d expect to handle this smoothly.

Focus management is one of those invisible, tricky parts of UI that make or break accessibility. Behind the scenes, design systems invest surprisingly complex logic to make sure keyboard users never lose their spot or get trapped.

Let me walk you through what I learned digging into how popular design systems manage focus internally, the kinds of focus trap bugs that still sneak in, and how you can debug these issues in your own complex components.

Why Focus Management Is Harder Than It Looks

On the surface, managing focus sounds simple: when a user tabs, move focus to the next logical element. When a modal opens, focus the first input. When it closes, return focus back.

But under the hood, several tricky things happen:

Focus loss: When you remove or hide elements, the browser may move focus unexpectedly or nowhere at all.
Focus traps: Modals and popovers often want to trap focus inside, so keyboard users can’t tab out accidentally. But implementing this trap correctly is subtle.
Nested components: Complex component trees with nested modals, popovers, dropdowns, and tooltips can confuse the browser’s native focus order.
Dynamic DOM changes: Reactivity, animations, and mounting/unmounting components can cause focus to jump or disappear.

The result? Bugs like keyboard users getting stuck inside a modal, focus jumping unpredictably, or focus disappearing completely.

Peek Under the Hood: How Design Systems Manage Focus

I looked into a few popular design systems , think Material UI, Chakra UI, and Reach UI , and here’s how they tackle the problem.

1. Focus Scope and Focus Trap

Most systems create a "focus trap" around modals and popovers. This means:

They listen to keyboard events, especially Tab and Shift+Tab.
When the user tabs forward from the last focusable element inside the trap, they move focus back to the first.
When the user tabs backward from the first element, they move focus to the last.

This cyclical focus prevents the keyboard from escaping the modal unintentionally.

Underneath, they either:

Use invisible sentinel elements (focus sentinels) before and after the trap to catch tab events.
Or listen to keydown events and manually call event.preventDefault() and focus() to redirect.

Here’s a simplified example:

function trapFocus(container) {
  const focusableElements = getFocusableElements(container);
  container.addEventListener('keydown', e => {
    if (e.key !== 'Tab') return;

    const focusedIndex = focusableElements.indexOf(document.activeElement);
    if (e.shiftKey && focusedIndex === 0) {
      e.preventDefault();
      focusableElements[focusableElements.length - 1].focus();
    } else if (!e.shiftKey && focusedIndex === focusableElements.length - 1) {
      e.preventDefault();
      focusableElements[0].focus();
    }
  });
}

2. Restoring Focus on Close

Good design systems save the currently focused element before opening a modal or popover and restore focus to it when the overlay closes.

This seems straightforward but can get tricky when the original element unmounts or the DOM changes.

3. Managing Focus on Mount

When a modal opens, the ideal is to focus the first interactive element inside. But what if there’s no focusable element? Or the element appears after an animation?

Some systems wait until the content is fully rendered or use a setTimeout to delay focusing.

Others allow you to specify which element should receive focus.

4. Handling Nested Focus Traps

What if you have a modal inside a modal? Or a dropdown inside a popover?

Design systems keep track of nested traps using stacks. The most recently opened trap is active, while others are paused or disabled.

This ensures keyboard navigation respects the innermost overlay first.

Common Focus Trap Bugs and What Causes Them

Despite best efforts, focus bugs still happen, especially in custom or complex UIs.

Here are some patterns I’ve seen:

The Phantom Focus Bug

Focus disappears completely. Keyboard users tab, but nothing highlights.

Usually caused by:

The focused element being removed or hidden without focus moving elsewhere.
Focus being moved to a non-focusable container.
Timing issues where focus is set before the element is in the DOM.

The Focus Loop Break

Tabbing forward or backward escapes the trap unexpectedly.

Often caused by:

Missing or broken sentinel elements.
Multiple event listeners fighting over focus.
Nested traps not properly prioritized.

The Focus Trap Lock

Focus gets stuck inside a component with no way out.

Caused by:

Failing to restore focus to the element that opened the trap.
Keyboard handlers swallowing Tab or Shift+Tab but not redirecting focus.
Overly aggressive focus locking when multiple overlays are open.

Debugging Focus Issues in Complex Trees

When your UI has nested components, portals, and lots of dynamic elements, debugging focus gets tricky.

Here’s a practical approach:

1. Visualize Focus

Use Chrome DevTools or Firefox to inspect the focused element:

In DevTools console, document.activeElement tells you where focus currently is.
Add a global CSS style like *:focus { outline: 2px solid hotpink !important; } to clearly see focus.

2. Log Focus Events

Listen for focusin and focusout on the document to track focus movement:

document.addEventListener('focusin', e => console.log('Focus in:', e.target));
document.addEventListener('focusout', e => console.log('Focus out:', e.target));

This helps catch unexpected focus jumps or losses.

3. Check Focusable Elements

Run a quick helper to list focusable elements inside your trap:

function getFocusableElements(container) {
  return [...container.querySelectorAll(
    'a[href], button:not([disabled]), textarea, input, select, [tabindex]:not([tabindex="-1"])'
  )];
}

Make sure you actually have focusable elements where you expect.

4. Inspect Event Listeners

Use DevTools to see which event listeners are attached to trap elements. Conflicting listeners can break focus management.

5. Test Keyboard Navigation Manually

Slowly tab through your UI and watch focus move. Try shift+tab. Notice where focus gets stuck or lost.

6. Look for Portals and DOM Moves

Elements rendered via portals or outside the normal DOM flow can confuse focus. Make sure your focus trap accounts for that.

A Real-World Example: Debugging a Focus Trap Bug in a Modal

I recently helped debug a modal that sometimes lost focus after opening.

The symptoms:

Open modal
Keyboard focus briefly appeared on the first button
Focus disappeared and tabbing did nothing

After some digging:

The modal content was rendered asynchronously with a slight delay.
The focus trap attempted to focus the button immediately on open.
Because the button wasn’t in the DOM yet, focus landed nowhere.

The fix:

Delay the initial focus call until after the modal content mounted.
Use a useEffect hook with dependencies on modal open state.

useEffect(() => {
  if (isOpen) {
    const timer = setTimeout(() => {
      firstButtonRef.current?.focus();
    }, 0);
    return () => clearTimeout(timer);
  }
}, [isOpen]);

That tiny delay made all the difference.

Wrapping Up

Focus management is a delicate balancing act hidden under the hood of every accessible UI component. Design systems invest a lot of subtle logic to keep keyboard users on track, avoid traps, and restore focus correctly.

If you build custom components or integrate third-party design systems, understanding these mechanisms helps you avoid nasty focus bugs and debug them faster when they do appear.

Keep an eye on:

Focus traps and how Tab/Shift+Tab keys behave
Focus restoration after overlays close
Timing issues with dynamic rendering
Nested traps and portals

And don’t forget to test keyboard navigation as early and often as you can.

Your keyboard users will thank you.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

How Browsers Handle Keyboard Focus Navigation with tabindex -1 and aria-activedescendant

Srikar Phani Kumar Marti — Wed, 23 Sep 2026 10:46:08 +0000

Ever been stuck debugging a custom dropdown or a combo box that ignores keyboard focus in weird ways? Maybe you made the list items tabindex="-1" so they’re not in the tab order, and relied on aria-activedescendant to point to the selected item. But then, pressing arrow keys doesn’t update the screen reader’s focus the way you expect. Or worse, the browser’s native focus ring seems to vanish.

I hit exactly this while building a complex widget with a roving tabindex pattern. It looked perfect visually, but keyboard users and screen reader users got lost. Turns out, understanding how browsers handle tabindex="-1" and aria-activedescendant isn’t just about reading specs , it’s about grasping what the browser really does with keyboard focus under the hood.

Let me share what I learned about these two key pieces, how browsers manage focus, and how you can spot and fix common pitfalls.

The curious case of tabindex="-1"

You probably know: tabindex="0" makes an element keyboard focusable in the natural tab order. tabindex="-1" makes an element focusable programmatically, but skips it in the tab sequence.

That sounds straightforward. But here’s the catch:

You can call .focus() on a tabindex="-1" element, and it accepts keyboard focus.
But pressing Tab will never land on it.
Some browsers show the focus ring only for keyboard-initiated focus (Tab key), so focusing programmatically might hide the ring.

Why use tabindex="-1" at all? Because sometimes you want to move focus behind the scenes , like when a custom widget manages selection and keyboard navigation internally.

Example: A combo box where the input is focused, but the active item in the dropdown is not focused in the DOM, only referenced via aria-activedescendant. The list items have tabindex="-1" so they’re not tabbable, but can be focused by scripts if needed.

What about aria-activedescendant?

aria-activedescendant is a little-known but powerful ARIA attribute. It tells assistive technologies: "Hey, the element with this id inside me is the active item." The focus stays on the container, but the screen reader virtually moves focus to the referenced element.

This is crucial for widgets like listboxes or comboboxes where focus should remain on the input or container, but the active selection changes.

However, aria-activedescendant only works if the container element itself is keyboard focusable (usually tabindex="0" or naturally focusable). If the container isn’t focused, the screen reader has no anchor to follow.

How browsers actually manage keyboard focus here

Here’s the key: browsers track a single focused element in the DOM , the one that receives keyboard events, shows the native focus ring, and is the anchor for assistive tech.

When you set aria-activedescendant on that focused element, screen readers use it to redirect their virtual focus indication to the referenced item.

But the referenced item itself is not focused. It’s just pointed to.

If you try to focus an item with tabindex="-1" programmatically (like calling .focus()), that item becomes the browser focus target. But if you want to keep the input focused and just update the virtual active descendant, don’t call .focus() on the list item.

This distinction matters because:

The native focus ring appears on the focused element (the container or input), not the active descendant.
Keyboard events go to the focused element.
Screen readers announce the active descendant as the "current item" inside the container.

Common traps and debugging tips

Trap 1: Forgetting to focus the container

If your container element (the one with aria-activedescendant) isn’t focused, screen readers won’t follow the active descendant. Your list items might update visually, but the a11y focus won’t move.

Fix: Make sure the container is focusable (tabindex="0" or native) and programmatically focus it on widget open.

Trap 2: Setting tabindex="-1" on active items and calling `.focus()`

If you call .focus() on a tabindex="-1" list item, you move actual DOM focus there, which breaks keyboard input on the container.

Fix: Instead of moving DOM focus, update the container’s aria-activedescendant to point to the active item. Keep focus on the container.

Trap 3: Expecting native focus ring on active descendant

Browsers don’t show the native focus ring on the active descendant because it’s not actually focused.

Fix: Use CSS styles on the active item to highlight it visually. Use :focus-visible on the container for keyboard focus ring.

Trap 4: Keyboard event handling confusion

Since keyboard events go to the focused container, your widget’s keyboard logic must listen on the container, not list items.

Fix: Attach keyboard event handlers to the container and update aria-activedescendant accordingly.

Putting it all together: a concrete example

Imagine a custom listbox implemented like this:

A <div role="listbox" tabindex="0" aria-activedescendant="item-3"> is the keyboard focus target.
Inside are <div role="option" id="item-1" tabindex="-1"> elements.
User presses ArrowDown.
Widget code updates aria-activedescendant to "item-4", but does NOT call .focus() on that option.
The container remains focused, keyboard events continue to work, and screen readers announce the newly active item.

This pattern makes keyboard navigation smooth and accessible.

Why browsers chose this design

Managing a single focused element reduces complexity for assistive tech and keeps keyboard event routing predictable.

If every interactive item could be focused in the DOM, keyboard navigation would become chaotic in complex widgets.

aria-activedescendant lets you keep one focus anchor but still indicate selection changes inside a composite widget.

Wrapping up

If you’re building custom widgets, understanding the interplay of tabindex="-1" and aria-activedescendant is a game changer.

Make sure:

The container is focusable and focused.
Keyboard events are handled on the container.
You update aria-activedescendant to reflect the active item.
You never move DOM focus to the active item itself.
Visual highlight styles compensate for missing native focus ring on active descendants.

With this clarity, you’ll avoid subtle bugs, make your widgets friendlier to keyboard and screen reader users, and make debugging focus issues way less painful.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

Decoding the Accessibility Tree in Shadow DOM: Challenges and Solutions

Srikar Phani Kumar Marti — Mon, 21 Sep 2026 10:48:17 +0000

Ever had that moment where you build a shiny web component with Shadow DOM, test it in your browser, and everything looks perfect visually , but when you use a screen reader, your component feels like a black box? The screen reader either skips it entirely or reads confusing information.

I hit this exact wall recently. My custom dropdown was gorgeous, encapsulated, and well-structured. But accessibility testing with VoiceOver and NVDA revealed a frustrating truth: the accessibility tree didn’t expose my component’s internals correctly. Why? Shadow DOM.

Let me walk you through what’s really going on under the hood with the accessibility tree and Shadow DOM, why your screen reader might be getting lost in the shadows, and practical steps I took to fix it.

The accessibility tree: your UI’s secret map

You might be familiar with the DOM tree , the nested structure of HTML elements your browser renders. But assistive technologies don’t read the DOM directly. Instead, browsers build a parallel structure called the accessibility tree.

This tree distills the UI into semantic roles, states, and properties meaningful to screen readers, magnifiers, and other AT. It merges HTML semantics, ARIA attributes, and some computed styles.

When you press Tab or listen with a screen reader, you’re hearing the accessibility tree’s story, not the raw DOM.

Shadow DOM: encapsulation’s double-edged sword

Shadow DOM lets you build self-contained components. It hides implementation details, styles, and markup inside a shadow root, preventing conflicts and accidental overrides.

But this encapsulation comes at a cost. The shadow root acts like a boundary that the browser’s accessibility tree builder must navigate carefully. Not every node inside a shadow root is necessarily exposed to assistive tech.

Why Shadow DOM can break accessibility trees

Here’s the kicker: when a browser constructs the accessibility tree, it treats shadow boundaries differently than light DOM. Some elements inside shadow roots may be omitted or flattened depending on browser heuristics and the component’s ARIA usage.

For example, if your shadow root contains a button element but you don’t expose it properly, the screen reader may see just a generic container or nothing at all.

Different browsers and screen readers handle this with subtle differences, making debugging extra tricky.

How I debugged the shadow accessibility mess

I started by inspecting the accessibility tree. Chrome DevTools has an Accessibility pane that shows the accessibility tree hierarchy. I compared what was inside my component’s shadow root to what was actually exposed.

I found:

The shadow root was represented as a node but its internals were missing or collapsed.
ARIA roles I set inside the shadow root weren’t picked up.
Keyboard focus was trapped or skipped unexpectedly.

This told me the accessibility tree builder wasn’t bridging the shadow boundary properly.

Strategies to fix Shadow DOM accessibility

1. Use `delegatesFocus` when creating your shadow root

When you create a shadow root with element.attachShadow({ mode: 'open', delegatesFocus: true }), it allows the shadow DOM to delegate focus to internal elements. This helps keyboard users and screen readers interact with inner controls naturally.

2. Expose semantics explicitly with ARIA

Inside your shadow DOM, use ARIA roles, properties, and states carefully. For example, if your shadow root wraps a listbox, mark the container with role="listbox" and internal items with role="option".

But remember: ARIA can’t fix everything. It’s better to use native semantics where possible.

3. Use `aria-hidden` and `tabindex` strategically

Sometimes, elements inside the shadow root should be hidden from the accessibility tree (like decorative wrappers). Mark them with aria-hidden="true".

Also, ensure only interactive elements inside the shadow root have tabindex="0" or greater, so focus doesn’t get lost.

4. Flatten the accessibility tree with `::part` and `::slotted`

The ::part and ::slotted pseudo-elements let you expose parts of your shadow DOM to styling and accessibility.

By exposing interactive parts via part, you let assistive tech recognize them more easily. Slotted content from light DOM is incorporated in the accessibility tree too.

5. Test across browsers and screen readers

Accessibility tree handling varies. Test with Chrome + NVDA, Safari + VoiceOver, Firefox + Orca, etc. Tools like the Accessibility Insights browser extension help visualize the accessibility tree.

A concrete example: making a shadow dropdown accessible

Here’s a simplified pattern I used for a dropdown inside Shadow DOM:

const root = this.attachShadow({ mode: 'open', delegatesFocus: true });

root.innerHTML = `
  <div role="listbox" tabindex="0">
    <div role="option" tabindex="-1">Option 1</div>
    <div role="option" tabindex="-1">Option 2</div>
  </div>
`;

The listbox container is focusable and has the right role.
Each option is marked with role="option" and is not focusable by tab (tabindex="-1") but focus is managed programmatically.

This setup showed up correctly in the accessibility tree and the screen reader announced options as expected.

Final tip: Shadow DOM doesn’t have to be an accessibility black hole

Shadow DOM can feel like a barrier to accessibility, but with some care, you can build components that communicate clearly with assistive tech.

Use browser devtools to peek at the accessibility tree, leverage delegatesFocus, ARIA roles, and test with real screen readers early and often.

Once you decode how shadow boundaries shape the accessibility tree, you’ll avoid surprises and build components everyone can use.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

AI-Powered Frontend Debugging Tools: How They Work, What They Fix, and When to Watch Out

Srikar Phani Kumar Marti — Thu, 17 Sep 2026 10:41:57 +0000

Ever been stuck on a frontend bug that just wouldn’t quit? You try console.logs, step through the code, and maybe even rubber-duck your way through it. Then you hear about AI-powered debugging tools that claim to read your code, inspect live data, and suggest fixes. Sounds magical, right?

I recently took a deep dive into how these AI assistants actually work under the hood, what makes them useful, and the pitfalls that caught me off guard. Spoiler: they can speed up your debugging but can also lead you into traps if you don’t keep your wits about you.

The familiar frustration: Debugging frontend bugs is often a guessing game

Imagine you have a React app where a button click sometimes fails silently. No errors in the console, no obvious clues. You add console.logs, inspect props, trace event handlers , but the cause remains elusive.

This exact scenario is where AI debugging tools shine. They promise to analyze your code, runtime state, and sometimes even network requests to offer targeted hints or code fixes.

But how do they do it?

How AI debugging assistants peek under the hood

At their core, these tools combine two main things:

Code understanding: They parse your source files (JavaScript, JSX, CSS) to build a model of your app’s structure, functions, and data flow.
Runtime data analysis: They hook into your app as it runs , collecting error logs, inspecting variable values, event traces, or even performance stats.

Then they feed all this into a large language model (LLM), like GPT-4 or specialized code models, prompting it with your code snippets and runtime context.

The AI tries to figure out what the bug might be and suggests fixes or debugging steps. Some tools go further and generate patch diffs or automated tests.

Concrete example: Debugging a mysterious state update bug

I tested one tool on a React component where a state update didn’t trigger a re-render. The AI assistant:

Parsed the component code to understand state declarations and effects.
Looked at console logs and event handlers.
Suggested that a state variable was mutated directly instead of replaced, causing React to skip the re-render.

The suggestion included a code snippet showing how to create a new state object instead of mutating the existing one. That was exactly the bug.

This saved me a few rounds of trial-and-error.

What makes these AI tools helpful?

Context awareness: Unlike generic Stack Overflow searches, they see your exact code and runtime environment.
Interactive debugging: Some let you ask follow-up questions or request code explanations.
Speed: They can generate hypotheses faster than manual debugging.
Learning aid: Seeing AI’s reasoning can teach you new techniques or API usages.

But watch out: AI debugging isn’t foolproof

AI models hallucinate , they sometimes confidently suggest fixes that don’t actually work or misinterpret the code context.

In one case, the assistant suggested adding a missing import that wasn’t actually missing, which would have caused a new error.

Also, many AI tools have limited visibility:

They don’t truly run your code in a debugger, so can’t catch runtime side effects reliably.
They may lack access to complete app state or external APIs.
They sometimes treat symptoms, not root causes.

Blindly applying AI-generated fixes can introduce subtle bugs or security risks.

How to get the most out of AI debugging assistants

Use their suggestions as hypotheses, not gospel truth. Always review and test.
Combine AI insights with traditional debugging tools , breakpoints, performance profilers, network inspectors.
Feed the AI rich context: include relevant code snippets, error messages, and runtime logs.
Be wary of fixes that feel too good or too generic.

What this means for your developer workflow

AI debugging tools can become a handy pair of extra eyes , especially for tricky frontend bugs where code and runtime state interplay is complex.

They won’t replace your intuition or understanding but can speed up the cycle of forming and testing hypotheses.

As these tools evolve, expect tighter integration with editors, browsers, and CI pipelines, making debugging more interactive and data-driven.

Final thoughts

I’m excited about AI’s potential to tame frontend bugs, but I’m also cautious. These assistants are powerful new teammates but not omniscient gurus.

Keep your debugging skills sharp, test everything thoroughly, and use AI suggestions to supplement, not replace, your developer judgment. That’s how you’ll turn AI debugging tools from a neat novelty into a trusted part of your toolbox.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

ARIA Role Inheritance and Override: How Browsers Resolve Conflicting Semantics

Srikar Phani Kumar Marti — Wed, 26 Aug 2026 13:37:59 +0000

Ever had that moment where you slap an ARIA role on an element, only to find your screen reader ignores it or reads something totally unexpected? You double-check your markup, and then notice you also have some nested roles, or conflicting aria attributes nearby. What’s going on?

I ran into this while fixing accessibility bugs on a client site. A button inside a custom widget had role="button" but also aria-haspopup="menu" , and the screen reader would announce "menu" instead of "button." Digging in, I realized that the way browsers handle ARIA roles and properties isn’t just about what you explicitly set on an element. There’s a whole system of inheritance, overrides, and conflict resolution happening under the hood.

Let’s talk about how browsers actually resolve ARIA roles and properties when there are conflicts, and what that means for you when debugging accessibility issues.

The tangled web of ARIA roles and properties

ARIA roles describe what an element is to assistive technology. For example, role="button" tells a screen reader this element behaves like a button. Other roles include menu, checkbox, dialog, and so on.

But ARIA also has properties and states, like aria-haspopup, aria-checked, or aria-expanded, that modify or add semantic information.

The confusion starts when you put multiple roles or conflicting properties on the same element, or when nested elements define roles that might clash.

Here’s the kicker: an element can only have one computed role. While you can set multiple roles explicitly in your markup (like via role="button menu", which is invalid), browsers use a priority and inheritance system to pick one.

How browsers pick the winning ARIA role

The spec gives some guidelines, but browser implementations differ subtly. Here’s the gist:

Explicit role attribute wins: If you set role on an element, that role is the first candidate.
Implicit role fallback: If no explicit role is set, browsers may infer a role based on the tag name and attributes (like <button> implicitly has role="button").
Special roles override generic ones: Some roles have higher precedence. For example, alert overrides region.
ARIA role inheritance: Roles do not literally inherit like CSS properties, but some ARIA properties do affect descendants’ semantics.

For example, if you have role="menu" on a container and inside it a child with role="menuitem", the child’s role is explicit and independent.

What about conflicting ARIA properties?

This is where things get tricky. Properties like aria-haspopup can influence what screen readers announce.

In my example, adding aria-haspopup="menu" to a button tells the screen reader the button controls a menu , sometimes causing it to announce "menu" or "button with menu." But if you also set role="menu" on the same element, the role wins and it treats the element as a menu, not a button.

In other cases, properties can override or augment roles:

aria-checked on a checkbox or switch controls the checked state.
aria-expanded on a disclosure widget signals whether it’s open.

But if the role and the ARIA properties don’t align, screen readers may behave unpredictably.

Under the hood: the accessibility tree and role resolution

The secret sauce is the accessibility tree , a parallel structure browsers build from the DOM, CSS, and ARIA attributes that assistive tech consumes.

When the browser parses the DOM:

It looks for explicit roles on elements.
If absent, it infers implicit roles.
It collects ARIA properties, validating them against the role.
It resolves conflicts:
- Multiple roles aren’t allowed; the browser picks one by priority or last-known override.
- Conflicting properties may be ignored or cause fallback behavior.

This process can differ slightly between browsers and screen readers, which is why your accessibility testing must include multiple platforms.

Debugging tips: How to see the computed ARIA role and properties

Feeling lost? Here’s how to peek under the hood:

Use browser devtools accessibility pane: Chrome and Firefox have accessibility inspectors that show the computed role, name, states, and properties for any element.
VoiceOver or NVDA output: Listen carefully for what role and state the screen reader announces.
Accessibility tree snapshots: Tools like the Accessibility Object Model (AOM) inspector or axe-core can reveal discrepancies.

For example, in Chrome DevTools:

Right-click your element and inspect.
Go to the "Accessibility" tab.
See the "Computed Properties" , it shows the effective role and ARIA states.

If the computed role isn’t what you expect, check for conflicting role attributes on the same or ancestor elements.

Common pitfalls and how to avoid them

Don’t mix roles on the same element: Stick to one explicit role. If you need nested roles, use child elements.
Align ARIA properties with the role: Don’t add aria-haspopup="menu" on an element with role="menu"; it’s redundant and confusing.
Use native semantics when possible: Native HTML elements have implicit roles and states that assistive tech understands well.
Test with multiple screen readers: Behavior varies, so verify your ARIA usage under real conditions.

Why does this matter?

Misusing ARIA roles and properties can confuse users relying on assistive technology. Overriding or conflicting roles may cause screen readers to announce the wrong widget type, breaking navigation and interaction.

Understanding how browsers resolve these conflicts helps you write cleaner, more predictable accessible code.

Next time your ARIA role isn’t behaving as expected, remember it’s not just the markup but how the browser builds the accessibility tree and resolves those roles and properties. Use the tools to inspect what’s really going on, and keep your roles clear and consistent.

Accessibility isn’t just about adding attributes , it’s about making sure those attributes speak clearly and consistently to the user’s assistive technology.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

Optimizing Keyboard Navigation in Complex Web Apps: Techniques and Debugging Tools

Srikar Phani Kumar Marti — Tue, 25 Aug 2026 13:03:52 +0000

Ever found yourself tabbing through a complex web app only to get trapped inside a modal, or worse, see the focus jump erratically like it’s playing hide and seek? I’ve been there, building custom widgets that looked sleek but turned into nightmares for keyboard users.

It’s one thing to have basic tab order working. It’s another story entirely when you have nested widgets, dynamic content, or custom keyboard shortcuts. You want your app to feel smooth and predictable for keyboard users, but the reality is often a tangled mess of tabindexes, event handlers, and accessibility quirks.

In this post, I’ll share what I learned about optimizing keyboard navigation in complex web apps. We’ll dive into techniques for managing focus order, handling keyboard events gracefully, and using browser and screen reader tools to track down the root causes of weird focus or event issues.

When Keyboard Navigation Gets Messy

Picture a custom dropdown inside a modal that itself lives inside a tabbed interface. You press Tab expecting to move logically through the UI, but suddenly the focus skips the dropdown’s toggle or gets stuck inside the modal with no way out.

Why does this happen?

Incorrect tabindex values: Misusing or overusing tabindex can break natural tab flow.
No focus management on dynamic UI: When widgets open or close, focus should move appropriately, but often it doesn’t.
Keyboard event conflicts: Overlapping handlers steal or swallow keys like Escape or Arrow keys.
Screen readers and assistive tech nuances: What looks fine visually might confuse screen readers.

I recently ran into this while building a complex combo box. The toggle button was focusable, but pressing Down Arrow didn’t move focus to the list items as expected. Worse, closing the list didn’t return focus to the toggle button. Keyboard users were left puzzled.

The Core Principles Under the Hood

Focusability: What Can Receive Focus?

Native interactive elements like <button>, <input>, and <a href> are focusable by default. Non-interactive elements like <div> or <span> are not unless you add tabindex="0" or tabindex="-1".

tabindex="0" makes an element keyboard focusable in natural tab order.
tabindex="-1" makes an element focusable only programmatically (e.g., via .focus()) but skipped in tab order.

Using tabindex incorrectly often leads to confusing tab sequences or focus traps.

Managing Focus on State Changes

When you open a dropdown or modal, you should:

Move focus into the widget (usually to the first interactive element inside).
Trap focus within the widget if appropriate (e.g., modals).
Restore focus to the originating element when closing.

Doing this manually means calling .focus() at the right time and managing keyboard event handlers to trap or release focus.

Keyboard Event Handling

Keyboard events come in three flavors: keydown, keypress, and keyup. For custom navigation, keydown is typically the best place to intercept keys because it fires earliest.

Be careful to:

Prevent default browser behavior only when necessary.
Avoid conflicts with other handlers.
Respect modifier keys like Shift or Alt.

For example, intercepting Arrow keys to move focus inside a list requires preventing default scrolling but letting other keys pass through.

Tools to See What’s Really Happening

Browser DevTools - Focus Debugging

Modern browsers have features to inspect focus:

Elements panel: Inspect the currently focused element with document.activeElement in the console.
Accessibility pane: See what the browser exposes to assistive tech.
Tab order visualization: Some browsers or extensions highlight tabbable elements.

Try this in Chrome’s console:

console.log(document.activeElement);

or even add event listeners to log focus changes:

document.addEventListener('focusin', (e) => {
  console.log('Focus moved to:', e.target);
});

This helps you verify where focus lands as you tab around.

Screen Reader Testing

Screen readers like NVDA (Windows), VoiceOver (macOS), or Narrator (Windows) expose how your app’s focus and roles are announced.

Turn on your screen reader and:

Tab through your app.
Listen for announcements.
Verify the focus highlights match what’s announced.

Discrepancies here often reveal mismatches between aria-* attributes and actual focus.

Keyboard Event Listeners in Debug Mode

Adding verbose logging on keyboard events can clarify which handlers run and in what order.

document.addEventListener('keydown', (e) => {
  console.log('Key down:', e.key, 'Target:', e.target);
});

Use this to detect if some handler is calling e.preventDefault() too early or swallowing events.

Practical Techniques to Fix Common Issues

1. Prefer Native Elements When Possible

Buttons, links, inputs come with built-in keyboard support. When you need custom widgets, start from a native element or at least use role and tabindex carefully.

2. Use `tabindex` Sparingly and Correctly

Avoid positive tabindex values (e.g., tabindex="1") as they reorder tabbing unpredictably.
Use tabindex="0" for elements that must be focusable in order.
Use tabindex="-1" for programmatic focus targets.

3. Implement Focus Management on Open/Close

When opening a dropdown or modal:

function openDropdown() {
  dropdownElement.style.display = 'block';
  dropdownElement.querySelector('li').focus();
}

When closing:

function closeDropdown() {
  dropdownElement.style.display = 'none';
  toggleButton.focus();
}

4. Trap Focus Inside Modals

Trap focus by listening to keydown for Tab and Shift+Tab:

document.addEventListener('keydown', (e) => {
  if (e.key === 'Tab') {
    // logic to cycle focus inside modal
    e.preventDefault();
  }
});

Libraries like focus-trap automate this.

5. Handle Arrow Keys and Other Navigation Keys

For list widgets, intercept Up/Down arrows to move focus between items:

function onKeyDown(e) {
  if (e.key === 'ArrowDown') {
    e.preventDefault();
    moveFocusToNextItem();
  }
}

Make sure to update aria-activedescendant or focus accordingly.

Wrangling a Real Bug: A Case Study

In my combo box, pressing Down Arrow didn’t move focus to the list items. Turns out I had:

The toggle button focusable with tabindex="0".
The list container with tabindex="-1" but no focus shifting on open.
Keyboard handler on the toggle button that didn’t prevent default or move focus.

Fix:

Added code to focus the first list item on open.
Prevented default on Arrow Down.
Managed aria-expanded and aria-controls attributes properly.

Once fixed, keyboard navigation felt natural and predictable.

Wrapping Up

Keyboard navigation in complex apps is tricky because you’re fighting the browser’s natural tab order, your app’s dynamic UI, and the expectations of assistive tech users.

By understanding focusability, carefully managing focus on UI state changes, and using browser and screen reader tools for debugging, you can make keyboard navigation smooth and reliable.

Next time your keyboard users get lost or stuck, you’ll have a better idea of where to look and how to fix it.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

CSS Container Queries: How Browsers Calculate and Recalculate Styles

Srikar Phani Kumar Marti — Mon, 24 Aug 2026 10:38:55 +0000

Ever had a layout break because a component looked perfect on your screen but warped on a colleague’s? Or tried to build a responsive widget that adapts to its container , not just the viewport , only to realize CSS media queries don’t cut it?

That’s exactly where CSS container queries come in. They let you apply styles based on the size of a container element instead of the whole viewport. It feels like magic until you hit bugs or weird reflows and start wondering: how exactly do browsers figure out when to apply those styles? How do they know the container size changed, and what happens next?

I spent a few weeks poking around browser engines and experimenting with container queries in real projects. Here’s what I learned about the mechanics under the hood, how browsers detect container resizes, what triggers style recalculations, and how to debug tricky issues.

When container queries hit the scene

Imagine you have a card component inside a sidebar. The sidebar can be narrow or wide. You want the card’s content to switch layout based on the card’s actual width , not the viewport width.

Previously, this was a headache. You’d either need JavaScript resize listeners or complex hacks. Now, with container queries, you write something like:

.card {
  container-type: inline-size;
}

@container (min-width: 300px) {
  .card {
    display: flex;
    flex-direction: row;
  }
}

Perfect. But how does the browser know when the card’s size crosses that 300px threshold?

The container query workflow inside browsers

At a high level, browsers treat container queries as a new kind of style condition. But unlike media queries , which depend on the viewport or device , container queries depend on the size of the container element itself.

Here’s the rough flow:

Container detection: The browser looks for elements styled with container-type. This tells it which elements are containers and what dimension (inline-size, block-size, or both) to watch.
Size measurement: On layout, the browser measures those container elements’ dimensions.
Style matching: When applying styles, the browser evaluates @container rules using the measured container size instead of viewport size.
Style recalculation: If the container size changes, the browser reevaluates container queries for all descendants that rely on that container.
Layout and paint: If styles changed, it triggers layout and paint updates as usual.

How does the browser detect container size changes?

This is the trickiest part. Browsers don’t constantly measure every container element on every frame , that would tank performance.

Instead, they rely on a combination of mechanisms:

Intrinsic size changes: If the container’s content or style changes in a way that affects its size, the layout engine notices during its normal flow.
Explicit resize observation: Browsers implement something similar to the Resize Observer API internally to detect size changes on container elements. When a container’s size changes, the browser marks it as needing container query reevaluation.
Cached sizes: To avoid thrashing, browsers cache container sizes and only trigger container query reevaluation if sizes actually differ beyond subpixel rounding.

This means if your container’s width changes from 290.4px to 310.1px, that crossing of the 300px threshold triggers new container query matches.

What happens when a container size changes?

When a container’s size changes:

The browser schedules a style recalculation focused on container queries inside that container.
It reevaluates any @container rules whose conditions depend on that container.
If styles for some elements change, it triggers a layout update for those elements and their children.
Finally, it paints the updated parts.

Since container queries can cascade, a single container size change might ripple to multiple nested containers, but browsers optimize to avoid unnecessary recalculations.

Under the hood: container queries and the rendering pipeline

Container queries introduce a dependency in the style system that looks like this:

Container size → style rules → layout → paint

This dependency means the browser’s rendering pipeline adds a new observation step:

During the style calculation phase, container sizes are used to pick styles.
If container sizes change, style recalculation happens, which can cascade to layout.

This is a subtle change compared to media queries because container queries depend on dynamic element size instead of global viewport size, which can change as a side effect of style or layout itself.

Real-world debugging tips for container queries

1. Check if your container actually has `container-type` set

Without this property, container queries silently don’t work. It’s not enough that you have @container rules , the container element must declare itself.

2. Verify the container’s size

Use DevTools to inspect the container’s box size. Sometimes padding, borders, or box-sizing cause the size to be different than you expect.

Resize your container manually (e.g., by resizing a pane or window) and watch if styles update.

3. Understand container sizing modes

container-type can be size, inline-size, or normal. The most common is inline-size, which watches width in horizontal writing modes.

If your @container queries use block-size conditions but your container only reports inline-size, those queries won’t match.

4. Beware of nested containers

If you have multiple nested containers, each with their own queries, the browser tracks each container separately. Styles inside nested containers can re-trigger layout, so be mindful of complexity.

5. Watch out for layout thrashing

If container queries cause style changes that affect container sizes themselves, you can get layout loops or jank.

Try to avoid container query rules that increase container size when the container size is already near your breakpoints.

6. Use Resize Observer for debugging

You can also add a ResizeObserver in your JS to watch container sizes and log when they change. This helps confirm when the browser detects size changes.

const container = document.querySelector('.card');
const ro = new ResizeObserver(entries => {
  for (let entry of entries) {
    console.log('Container size changed:', entry.contentRect.width);
  }
});
ro.observe(container);

What’s next with container queries?

Browser support is solid and growing, but some quirks remain:

Container queries don’t yet work inside iframes or shadow DOM in all browsers.
Performance is still evolving. Benchmark your layouts if you use many or deeply nested containers.
The spec may add more features like container query lists or interaction-based queries.

Wrap-up

Container queries feel like a breath of fresh air for responsive design that adapts to component size, not just viewport size. But under the hood, they add a new dimension to the browser’s rendering pipeline , tracking container sizes, recalculating styles dynamically, and triggering layout updates selectively.

Understanding how browsers detect container size changes and apply container query styles helps you avoid surprises and debug issues faster.

Next time your card flips layout on a size boundary, you’ll know exactly what’s going on inside the browser to make that happen.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

React Portals: How They Work and When to Use Them for Modals and Tooltips

Srikar Phani Kumar Marti — Wed, 19 Aug 2026 11:11:08 +0000

You’ve probably built a modal or tooltip in React and hit a weird snag: the overlay appears visually outside your usual component tree, but events don’t behave as you expect. Maybe clicks inside the modal don’t bubble the way you thought, or keyboard focus seems lost when you open it.

That’s React portals messing with your head , in a good way. They let you render children into a DOM node outside your React root, which is great for modals, tooltips, dropdowns, and other overlays. But under the hood, portals change the event propagation and focus flow in subtle ways.

I ran into this recently while debugging a modal that wouldn’t close on outside clicks. The culprit? A misunderstanding of how portals handle events and focus in the DOM.

Let me walk you through how React portals work, what happens to events and focus, and some practical debugging tips when using portals for modals and tooltips.

What Exactly Is a React Portal?

React portals are an escape hatch. Normally, React renders your component tree inside a single root DOM node , often <div id="root">. But what if you want a component somewhere else in the DOM, like a modal appended to document.body?

Portals let you do that:

ReactDOM.createPortal(children, container)

This tells React: render children into DOM container, outside the main React DOM tree.

Why?

Modals and tooltips often need to break out of parent containers that may have overflow: hidden or z-index stacking contexts.
They need to sit at a higher DOM level for proper layering and positioning.

So portals let you keep React’s declarative component model while placing DOM nodes where they need to be.

What Happens Under the Hood?

React internally keeps track of the portal’s target container. It renders the portal’s children into that container as real DOM nodes.

But React’s component tree and the DOM tree then diverge. Your React tree says "Modal is a child of App," but the DOM says "Modal is a child of document.body."

This divergence is the core of what trips people up.

Event Propagation Isn’t Broken , But It’s Different

Here’s the key: React uses a single event delegation system at the root container. Events bubble through the DOM, then React maps them back to components.

With portals, the DOM tree is split. The portal’s DOM nodes live somewhere else, outside the root container where React listens for events.

So how does React handle events from portal nodes?

React attaches event listeners at the root of each React render tree , and for portals, it attaches them at the portal’s container node too.

This means events inside a portal bubble through the portal container, then propagate to the React root container.

In practice, this usually works seamlessly, but there are some event propagation edge cases:

Events that rely on the DOM tree hierarchy (like native event bubbling) behave normally because the portal nodes are real DOM children of the portal container.
But React’s synthetic event system treats portal containers as roots for event delegation, so some event listeners might fire in different orders.

This explains why outside click detection on portals sometimes fails if you’re relying on event bubbling inside the React tree without accounting for the portal’s container boundaries.

Focus Management: The Invisible Trap

Modals and tooltips often trap focus for accessibility: when the modal opens, keyboard focus should move inside it, and tabbing should cycle within the modal.

Portals complicate this because the modal’s DOM nodes are outside the React root and its focus context.

Browsers don’t care about React internals , they only see DOM nodes. So focus will move normally, but your app’s logic to restore focus or detect focused elements needs to account for the portal container.

For example, if you try to detect clicks outside a modal by checking if the event target is inside your React tree, it won’t work , because the modal lives in a separate DOM subtree.

Also, keyboard navigation and focus outlines might behave unexpectedly if CSS styles or focus management code assume the modal is nested inside the React root.

Practical Debugging Tips for Portal-Based Modals and Tooltips

1. Use `ref` on the Portal Container

Keep a ref to the portal container DOM node (document.body or a div you created). When handling clicks or focus events, check if the event target is inside that container using container.contains(event.target).

This is more reliable than React tree checks.

2. Attach Event Listeners on the Portal Container

For outside click detection, attach mouse event handlers on the portal container or even document.

React’s synthetic events may not catch all events correctly when portals are involved, so sometimes native event listeners are more reliable.

3. Manage Focus Explicitly

When opening a modal:

Focus the first focusable element inside the portal.
Trap tab focus inside the portal container.
Return focus to the opener element when closing.

Use libraries like focus-trap-react or build your own with careful DOM traversal.

4. Watch for CSS Stacking Context Issues

Since portals render outside your main tree, your modal or tooltip might be affected by z-index, position, or overflow styles on ancestor nodes.

Debug with DevTools by inspecting the portal container and ancestors to ensure it’s visible and on top.

5. Beware of Event Ordering Differences

If you have both portal and non-portal components listening for the same events, event firing order might surprise you.

Test carefully and consider using native event listeners in tricky cases.

When Should You Reach for Portals?

Use portals when you need UI elements that:

Break out of clipping or stacking of parent containers
Need to be siblings of your root app node for layering
Require focus management separate from the main React tree

Modals, tooltips, dropdown menus, fullscreen overlays, and context menus are classic portal use cases.

If your popup content can stay within parent containers without clipping or z-index issues, portals might be overkill and add complexity.

A Real Debugging Story

I once built a tooltip that disappeared as soon as I clicked inside it , even though I had an outside click handler to close it only if the click was truly outside.

The problem was the click event inside the portal was bubbling to the portal container, but my handler was checking if the click target was inside the React component tree , which it wasn’t.

Solution: I switched to checking if the click target was inside the portal container DOM node instead. Suddenly, clicks inside the tooltip didn’t trigger the outside click handler.

That tiny change saved me hours of head-scratching.

Wrapping Up

React portals let you render components outside your main React root for UI elements like modals and tooltips. This is powerful but comes with quirks:

Event propagation crosses DOM boundaries differently than standard React tree events.
Focus management requires explicit handling because the portal’s DOM nodes are outside your main tree.
Debugging portal issues means thinking in terms of DOM containment and event flow outside React’s usual model.

Next time your modal misbehaves or your tooltip’s keyboard navigation feels off, remember: portals are working exactly as designed , but you might need to adapt your event and focus logic to their outside-the-tree reality.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

Debugging React Memoization: When useMemo and React.memo Backfire

Srikar Phani Kumar Marti — Mon, 17 Aug 2026 10:47:42 +0000

You’ve wrapped a component with React.memo or used useMemo to optimize rendering. You expect fewer renders, snappier UI, maybe even a better frame rate.

But then, surprise! Your component still re-renders way more often than you think it should. Or worse, it seems stuck showing stale props or state.

This exact problem had me banging my head against the wall recently. Memoization in React isn’t magic , it’s a subtle mechanism with traps that can silently backfire.

Why Memoization Exists in React

React components re-render when their parent renders, their props change, or their state updates. Sometimes you want to avoid unnecessary work when inputs haven’t changed.

React.memo is a higher-order component that shallowly compares props and skips rendering if they’re equal.

useMemo caches a computed value between renders, recomputing only when dependencies change.

Sounds straightforward, right? But the devil is in how equality is checked and dependencies are tracked.

The Shallow Equality Trap

React.memo does a shallow comparison of props using Object.is by default. That means it only compares primitive values or references, not deep object contents.

Here’s a classic example:

const MyComponent = React.memo(({ user }) => {
  console.log('Rendering', user.name);
  return <div>{user.name}</div>;
});

function Parent() {
  const user = { name: 'Alice' };
  return <MyComponent user={user} />;
}

You’d expect MyComponent to render once, right? Nope. Every render of Parent creates a fresh user object with a new reference, so React.memo sees different props and re-renders.

What’s going on?

React.memo compares the previous user prop and the new one by reference. Since Parent creates a new object inline, React.memo thinks props changed.

How to fix it?

Memoize the object outside render:

function Parent() {
  const user = React.useMemo(() => ({ name: 'Alice' }), []);
  return <MyComponent user={user} />;
}

Now MyComponent skips renders unless user changes.

When useMemo Doesn’t Memoize What You Think

useMemo works similarly , it caches a value between renders, recomputing only if dependencies change. But it’s easy to misuse.

Consider this snippet:

const memoizedValue = useMemo(() => computeExpensive(), [data]);

If data is an object or array recreated every render, your memoization fails because the dependency changes every time.

This is a common pitfall when you see useMemo not preventing expensive recalculations.

Debug tip:

Log your dependencies and check if their references are stable.

Stale Props and State Due to Memoization

Another tricky scenario: your memoized component doesn’t update when props seem to change.

This usually happens because of stale closures or incorrect dependency arrays.

Example:

const MyComponent = React.memo(({ onClick }) => {
  const handleClick = React.useCallback(() => {
    console.log('Clicked');
  }, []);

  return <button onClick={handleClick}>Click me</button>;
});

If the parent passes a new onClick prop every render but your component uses a memoized handleClick with an empty array, it might ignore the new prop.

What’s the solution?

Make sure callbacks and memoized values depend on all relevant props and state.

React.memo with Custom Comparison Functions

If your props are complex objects that change frequently but contain stable values, you can provide a custom comparator:

function areEqual(prevProps, nextProps) {
  return prevProps.user.id === nextProps.user.id;
}

const MyComponent = React.memo(Component, areEqual);

This lets you control when to skip renders more precisely.

But beware: writing incorrect comparators can cause subtle bugs where your UI doesn’t update as expected.

Debugging Memoization Issues Step-by-Step

Log Every Render

Add console.log inside your component to see when it renders.

Check Prop References

Log props before passing them to memoized components. Use console.log(prop, Object.is(prevProp, prop)) to check if references change.

Inspect Dependency Arrays

For useMemo and useCallback, ensure dependencies include everything used inside the function.

Use React DevTools Profiler

It highlights which components re-render and why. You can spot unexpected renders this way.

Try Removing Memoization

Temporarily remove React.memo or useMemo to see if behavior changes.

When Not to Use Memoization

Memoization isn’t free. It adds complexity and some overhead.

If your components are cheap to render or your app isn’t bottlenecked by rendering, memoization might be premature optimization.

Wrapping Up

React’s memoization tools are powerful but delicate. They rely on reference equality and correct dependencies. If you don’t get those right, you get surprise re-renders or stale UI.

The key is to treat memoization as a contract , you must keep references stable and dependencies accurate. When that contract breaks, React’s memoization works against you.

Next time your useMemo or React.memo seems broken, grab your console, check those references, and track down the sneaky object or function that’s tripping you up.

Happy debugging!

Helpful learning resources

MDN Web Docs
web.dev performance guidance
React documentation Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

Keyboard Accessibility in Custom Components: Implementing and Debugging Focus Management

Srikar Phani Kumar Marti — Wed, 12 Aug 2026 10:38:47 +0000

Ever tried tabbing through a custom dropdown or a fancy toggle switch you built, only to find the keyboard focus just skips over it, or worse, gets trapped inside with no way out? I’ve been there, frustrated by a UI that looked perfect but was a nightmare to navigate without a mouse.

Keyboard accessibility can easily slip through the cracks when you roll your own components. Native elements like <button> and <select> come with built-in keyboard behavior and focus handling baked in. Custom stuff? Not so much. You get the visuals, but the focus order, keyboard events, and screen reader cues? That’s all on you.

Let me walk you through the key challenges I ran into, how keyboard focus really works under the hood, and some concrete ways to implement and debug accessible keyboard navigation in custom UI components.

The focus trap: Why keyboard users get stuck or skipped

I once built a custom dropdown with divs and spans for styling freedom. It looked slick, but when I tested keyboard navigation, tabbing would jump right past it. Or sometimes the focus would enter the dropdown, but arrow keys didn’t move selection as expected. Worse, shift+tabbing out of the dropdown was impossible; the focus got stuck inside.

Why? Because by default, only certain elements are focusable , mostly interactive native elements like buttons and inputs. A div or span? Not focusable unless you add tabindex.

I had neglected to:

Make the dropdown toggle button focusable with tabindex="0" (or better, use a native <button>)
Manage keyboard events like ArrowUp, ArrowDown, Escape to open/close and navigate items
Control focus movement on open to the first menu item
Restore focus to the toggle when closing

Without explicit focus management, keyboard users either can’t reach the dropdown or get lost inside it.

How browser focus and tab order really work

Browsers assign a tab order based on the document’s focusable elements:

Native focusable elements (<button>, <input>, <a href>, etc.) come first
Elements with positive tabindex (rarely recommended)
Elements with tabindex=0 (focusable in DOM order)
Elements with negative tabindex are focusable programmatically but skipped in tab order

If your custom component’s parts lack tabindex=0 or aren’t native focusables, the keyboard will skip them.

Also, when you open something like a menu, you typically want to move focus into it programmatically (e.g., focus the first menu item). This prevents keyboard users from losing context.

Implementing keyboard support in custom components

Here’s a checklist I use when coding custom keyboard interactions:

Use semantic elements whenever possible. If your toggle behaves like a button, use <button>.
Make interactive elements focusable. Use tabindex="0" on divs or spans if needed, but sparingly.
Handle keyboard events explicitly. Listen for keydown events on your component, and respond to keys like Enter, Space, Arrow keys, Escape.
Manage focus on open/close. When a dropdown opens, move focus to the first item. When it closes, return focus to the toggle.
Trap focus if needed. For modal dialogs or complex widgets, keep focus inside until the user closes or presses Escape.
Use ARIA roles and attributes properly. role="menu", role="menuitem", aria-expanded, aria-haspopup, and aria-activedescendant help assistive tech understand your widget.

For example, for a custom dropdown:

<button
  aria-haspopup="listbox"
  aria-expanded={isOpen}
  onClick={toggleOpen}
  ref={toggleRef}
>
  Select an option
</button>
{isOpen && (
  <ul
    role="listbox"
    tabIndex={-1}
    ref={listboxRef}
    onKeyDown={handleKeyDown}
  >
    {options.map((option, i) => (
      <li
        key={option.id}
        role="option"
        tabIndex={focusedIndex === i ? 0 : -1}
        onClick={() => selectOption(option)}
        onFocus={() => setFocusedIndex(i)}
      >
        {option.label}
      </li>
    ))}
  </ul>
)}

In handleKeyDown, you’d manage ArrowUp/Down to move focusedIndex, Enter or Space to select, and Escape to close and return focus.

Debugging keyboard navigation woes

Testing keyboard accessibility is simple but powerful:

Use Tab and Shift+Tab to navigate through your app’s interactive elements.
Use screen reader tools to check announcements and focus highlights.
Inspect the Accessibility Tree with browser devtools to verify roles and focusability.

If tab skips your component, check:

Does the toggle have a native focusable element or tabindex="0"?
Are interactive items focusable and in tab order?
Are you accidentally using tabindex="-1" where you want tab to land?

If focus gets trapped:

Are you managing focus programmatically on open and close?
Do you have a focus trap or modal code that might be overzealous?

If keyboard events don’t work:

Are you listening for keydown instead of keypress or keyup? keydown is best for handling navigation keys.
Are you calling event.preventDefault() appropriately to avoid default scrolling or key behavior?

Browser devtools Accessibility pane lets you simulate keyboard focus and see the accessibility tree. Also, extensions like Axe or Lighthouse can flag common accessibility issues.

Beyond keyboard: Why accessibility is a team sport

Focus management is just one piece of accessibility. ARIA roles, visual focus indicators, announcements, and semantic HTML all matter. When you build custom UI, you’re responsible for recreating these affordances.

I learned that the best practice is to start with semantic HTML and enhance, rather than replace, native behavior. Use custom components only when necessary, and always test early and often with keyboard and assistive tech.

If you’re stuck, look at well-tested open source libraries like Reach UI or Radix UI. Their source code is a goldmine for how to handle focus and keyboard events right.

Final thoughts

Keyboard accessibility is not a checkbox , it’s a mindset. When you build a custom UI, imagine your app without a mouse. Walk through it with Tab. If you hit a blind spot, that’s where focus management needs work.

Fixing keyboard navigation bugs might feel tedious, but it makes your app usable by millions who rely on keyboards or assistive technology. And often, the fixes improve your code quality and UX for everyone.

So next time you craft a custom dropdown, toggle, or modal, don’t just make it look good , make sure you can tab through it cleanly, see where you are, and never get stuck.

Helpful learning resources

W3C WAI accessibility guidance
W3Schools accessibility tutorials
MDN Web Docs Originally published at Under The Hood. Get the next deep dive in your inbox: subscribe to Under The Hood.

DEV Community: Srikar Phani Kumar Marti

Design Systems and Accessibility: Mechanisms to Enforce Consistent Focus Management

Focus management is more than tabindex

How design systems enforce consistent focus

1. Centralized focus utilities

2. Focus context and state

3. ARIA integration

4. Keyboard event handling

When your app overrides break focus management

Debugging focus issues in design systems

Use browser devtools’ accessibility inspectors

Manual focus inspection

Check event listeners

Verify ref forwarding

Test with screen readers

Example: Focus trap in a modal

Wrapping up

Helpful learning resources

Understanding React’s useTransition: Mechanisms and Performance Implications

The developer moment: Why did my spinner randomly appear?

useTransition under the hood: marking updates as low priority

What happens in React’s scheduler?

The isPending flag: what you’re really tracking

When to use useTransition , and when not to

A concrete example: search input with and without useTransition

Debugging tip: React DevTools Profiler and isPending

What happens if you nest transitions or mix priorities?

Wrapping up

Helpful learning resources

Design Systems and Focus Management: Mechanisms to Avoid Focus Loss and Trap Bugs

Why Focus Management Is Harder Than It Looks

Peek Under the Hood: How Design Systems Manage Focus

1. Focus Scope and Focus Trap

2. Restoring Focus on Close

3. Managing Focus on Mount

4. Handling Nested Focus Traps

Common Focus Trap Bugs and What Causes Them

The Phantom Focus Bug

The Focus Loop Break

The Focus Trap Lock

Debugging Focus Issues in Complex Trees

1. Visualize Focus

2. Log Focus Events

3. Check Focusable Elements

4. Inspect Event Listeners

5. Test Keyboard Navigation Manually

6. Look for Portals and DOM Moves

A Real-World Example: Debugging a Focus Trap Bug in a Modal

Wrapping Up

Helpful learning resources

How Browsers Handle Keyboard Focus Navigation with tabindex -1 and aria-activedescendant

The curious case of tabindex="-1"

What about aria-activedescendant?

How browsers actually manage keyboard focus here

Common traps and debugging tips

Trap 1: Forgetting to focus the container

Trap 2: Setting tabindex="-1" on active items and calling .focus()

Trap 3: Expecting native focus ring on active descendant

Trap 4: Keyboard event handling confusion

Putting it all together: a concrete example

Why browsers chose this design

Wrapping up

Helpful learning resources

Decoding the Accessibility Tree in Shadow DOM: Challenges and Solutions

The accessibility tree: your UI’s secret map

Shadow DOM: encapsulation’s double-edged sword

Why Shadow DOM can break accessibility trees

How I debugged the shadow accessibility mess

Strategies to fix Shadow DOM accessibility

1. Use delegatesFocus when creating your shadow root

2. Expose semantics explicitly with ARIA

3. Use aria-hidden and tabindex strategically

4. Flatten the accessibility tree with ::part and ::slotted

5. Test across browsers and screen readers

A concrete example: making a shadow dropdown accessible

Final tip: Shadow DOM doesn’t have to be an accessibility black hole

Helpful learning resources

AI-Powered Frontend Debugging Tools: How They Work, What They Fix, and When to Watch Out

The familiar frustration: Debugging frontend bugs is often a guessing game

How AI debugging assistants peek under the hood

The `isPending` flag: what you’re really tracking

Debugging tip: React DevTools Profiler and `isPending`

Trap 2: Setting tabindex="-1" on active items and calling `.focus()`

1. Use `delegatesFocus` when creating your shadow root

3. Use `aria-hidden` and `tabindex` strategically

4. Flatten the accessibility tree with `::part` and `::slotted`

2. Use `tabindex` Sparingly and Correctly

1. Check if your container actually has `container-type` set

1. Use `ref` on the Portal Container