Proposal for triggerRef option and ARIA attribute automation to improve A11y

[jun094]

Hello, I'm a developer who has found overlay-kit to be incredibly useful. The declarative API has made managing overlay state a much more pleasant experience. I'd like to propose an enhancement to further this developer experience, specifically around accessibility.

The Problem

A core value of overlay-kit is abstracting away the boilerplate of overlay state management, as shown in the Code Comparison documentation.

However, to implement an accessible overlay, developers are still required to write repetitive boilerplate code to manage ARIA attributes.

Current Implementation:

function CurrentExample() {
  // 1. Separate state needed for aria-expanded
  const [isExpanded, setIsExpanded] = useState(false);
  const dialogId = useId(); // 2. Manual ID linking

  const handleOpen = () => {
    setIsExpanded(true);
    overlay.open(({ isOpen, close }) => (
      <Dialog
        id={dialogId}
        open={isOpen}
        onClose={() => {
          close();
          setIsExpanded(false); // 3. Manually update state on close
        }}
      />
    ));
  };

  return (
    <button
      onClick={handleOpen}
      aria-expanded={isExpanded}
      aria-controls={dialogId}
    >
      Open Dialog
    </button>
  );
}

This manual management can lead to mistakes, and is a bit of a departure from the simplicity that overlay-kit aims for.

Proposed Solution

I propose enhancing the overlay.open API to accept an optional triggerRef. When this ref is provided, overlay-kit would automatically manage the necessary ARIA attributes.

• Proposed API: overlay.open(Controller, { triggerRef?: React.RefObject<Element> })
• How it would work:
  1. When triggerRef is provided, overlay-kit internally generates an ID for the overlay and links it to the triggerRef element's aria-controls attribute.
  2. When the overlay is opened, it sets aria-expanded="true" on the triggerRef element.
  3. When the overlay is closed, it sets aria-expanded="false".

The Ideal API

This feature would allow developers to forget about ARIA attribute management and focus purely on their component's logic, resulting in cleaner and more declarative code.

Proposed Implementation:

function ProposedExample() {
  const triggerRef = useRef<HTMLButtonElement>(null);

  const handleOpen = () => {
    overlay.open(
      ({ isOpen, close }) => <Dialog open={isOpen} onClose={close} />,
      { triggerRef } // Just pass the ref, and accessibility is handled!
    );
  };

  return (
    <button ref={triggerRef} onClick={handleOpen}>
      Open Dialog
    </button>
  );
}

Benefits

• Eliminates boilerplate, allowing developers to be more productive.
• Automates ARIA implementation, reducing human error and ensuring a higher standard of accessibility out of the box.
• Extends the library's core value from "simplified state management" to a more holistic "simplified UI declaration."

This would be a non-breaking change, as the triggerRef option would be entirely opt-in. I believe this addition would significantly increase the value of overlay-kit.

I would love to hear the maintainers' thoughts on this proposal. I am also willing to contribute to a PR if this aligns with the project's roadmap.

Thank you!

[jungpaeng]

Hello. Thank you for your interest in overlay-kit and for sharing your valuable feature proposal.

However, there are a few points to consider regarding your suggestion.

---

1. ARIA requirements for different overlay components

• overlay-kit supports all overlays—not just Dialog, but also Menu, Tooltip, Popover, etc.
• Each component requires different ARIA attributes, so it’s difficult to handle every case automatically with a single triggerRef option.
• For example, according to the W3C guidelines, aria-controls is only required when a combobox is expanded or an element acts as a scroll container; it is not mandatory for Dialogs or Modals.
  • W3C Proposed Rule: aria-controls
• A similar issue has been discussed in Radix UI:
  • Menu trigger's aria-controls creates invalid html radix-ui/primitives#3013

2. Timing issue with aria-controls linkage

• Even if you generate an ID when calling overlay.open, the overlay won’t exist in the document until it actually renders.
• Some screen readers, like JAWS, require the aria-controls target element to be present immediately in the DOM. Toggling it only after the overlay opens may provide no benefit.
  • aria-controls support information

3. Warning when using aria-expanded

• There’s an example where applying aria-expanded to a Dialog/Modal triggered an accessibility audit warning.
  • Remove aria-controls and aria-expanded from modal disclosures ariakit/ariakit#925 (comment)
• Whether to use aria-expanded should be decided carefully based on the component’s role.

---

Considering the above, it is most reliable for developers to manage ARIA attributes themselves on a per-component basis.
However, we fully agree that writing repetitive boilerplate is burdensome. To address this, we’re planning to introduce a plugin architecture and provide a companion accessibility utility package.

We don’t have a firm timeline yet, but once our current workload stabilizes, we will begin development and make sure to incorporate your suggestions.
Thank you again for sharing this great idea!

[jun094]

Thank you for the detailed response and for sharing your long-term vision for a plugin architecture. I fully agree that it is the ideal solution.

However, I'd like to propose a pragmatic interim solution to address the boilerplate issue that developers currently face before the plugin system is ready. For developers today, repetitive boilerplate code is a real pain point, and while manual implementation using useOverlayData is possible, it requires repeated logic, which is contrary to overlay-kit's philosophy of "making development easier by reducing code."

To bridge this gap, I believe we could consider the following two-step approach:

1. Provide Official Guide Documents on Accessibility: First, providing official documentation with best-practice examples for making common overlay types like Dialog, Menu, and Tooltip accessible would be of immediate and significant value.
2. Introduce Helper Hooks: As a next step, the logic from the guides could be encapsulated into non-automated hooks like useDialogA11y() or useMenuA11y(). These hooks would only return pre-packaged prop objects, allowing developers to reduce boilerplate while maintaining full control over applying the props.

const { triggerProps, dialogProps } = useDialogA11y();

I believe this phased approach would immediately provide developers with clear and reliable patterns, and serve as a practical foundation for the eventual plugin package, all while avoiding the technical risks you mentioned.

Of course, this is just one thought on how to improve the developer experience, and we respect your roadmap and priorities.

Thank you again for the wonderful discussion. I look forward to seeing what's next for overlay-kit.

[son426]

Putting aria-controls aside — focus not returning to the trigger on close seems like a bigger deal.

"When a dialog closes, focus returns to the element that invoked the dialog"
— APG Dialog (Modal) / WCAG 2.4.3 (A) / Toss A11y Fundamentals – Modal)

Two questions:

1. Do you restore focus manually when using overlay-kit internally, or is this generally unhandled today?
2. Is the plugin architecture / a11y package @jungpaeng mentioned still on the roadmap? Would love to know where that stands. 🙏