Building Accessible UI Components in React: Chakra UI vs Headless UI vs React Accessible Accordion

When building React applications, accessibility (a11y) is not optional — it is a requirement. The packages @chakra-ui/react, @headlessui/react, and react-accessible-accordion all aim to solve accessibility challenges, but they approach the problem from different angles. Let's compare how they handle styling, composition, and specific patterns like accordions.

🎨 Styling Approach: Built-In vs Unstyled vs None

@chakra-ui/react comes with built-in styles based on a theme.

• You style components using style props directly on the component.
• It uses a CSS-in-JS solution under the hood (Emotion).
• Great for speed, but adds runtime styling overhead.

// chakra: Style props
import { Button } from '@chakra-ui/react';

function Submit() {
  return <Button colorScheme="teal" size="md">Submit</Button>;
}

@headlessui/react provides no styles at all.

• You must apply all classes yourself, usually with Tailwind CSS.
• This keeps the bundle smaller regarding CSS, but requires more setup.
• You get full control over the final look.

// headless: Utility classes
import { Switch } from '@headlessui/react';

function Toggle() {
  return (
    <Switch className="bg-blue-600">
      <span className="sr-only">Enable notifications</span>
    </Switch>
  );
}

react-accessible-accordion provides structure but minimal visual styling.

• It focuses on the logic and ARIA attributes for accordions.
• You are responsible for styling the container, buttons, and panels via CSS classes.
• Best when you only need the accordion logic without a full system.

// accordion: Custom classes
import { Accordion, AccordionItem, AccordionButton, AccordionPanel } from 'react-accessible-accordion';

function FAQ() {
  return (
    <Accordion>
      <AccordionItem>
        <AccordionButton className="custom-button">Question</AccordionButton>
        <AccordionPanel className="custom-panel">Answer</AccordionPanel>
      </AccordionItem>
    </Accordion>
  );
}

♿ Accessibility Logic: Automatic vs Manual Control

@chakra-ui/react handles accessibility automatically.

• Components come with correct ARIA roles and keyboard navigation built-in.
• You rarely need to think about focus management or screen readers.
• This reduces risk but limits customization of behavior.

// chakra: Auto a11y
import { Menu, MenuButton, MenuList, MenuItem } from '@chakra-ui/react';

function Nav() {
  return (
    <Menu>
      <MenuButton>Open</MenuButton>
      <MenuList>
        <MenuItem>Option 1</MenuItem>
      </MenuList>
    </Menu>
  );
}

@headlessui/react enforces accessibility patterns.

• It ensures correct ARIA attributes are applied, but you control the markup.
• If you break the required structure, it may warn or fail silently.
• Ideal for developers who understand a11y but want to avoid the boilerplate.

// headless: Enforced a11y
import { Menu, MenuButton, MenuItems, MenuItem } from '@headlessui/react';

function Nav() {
  return (
    <Menu>
      <MenuButton>Open</MenuButton>
      <MenuItems>
        <MenuItem>Option 1</MenuItem>
      </MenuItems>
    </Menu>
  );
}

react-accessible-accordion specializes in accordion a11y.

• It manages aria-expanded, aria-controls, and focus order specifically for accordions.
• It does not help with other components like modals or dropdowns.
• Good for isolated needs, but you must manage global a11y elsewhere.

// accordion: Specialized a11y
import { Accordion, AccordionItem, AccordionButton, AccordionPanel } from 'react-accessible-accordion';

function FAQ() {
  return (
    <Accordion>
      <AccordionItem>
        <AccordionButton>
          <span aria-hidden="true">+</span> Question
        </AccordionButton>
        <AccordionPanel>Answer</AccordionPanel>
      </AccordionItem>
    </Accordion>
  );
}

🧩 Composition: Component API vs Render Props

@chakra-ui/react uses a standard component API.

• You pass content as children or props.
• Easy to read and refactor for most React developers.
• Customization is done via the sx prop or theme extension.

// chakra: Standard children
import { Box, Text } from '@chakra-ui/react';

function Card() {
  return (
    <Box p={4} shadow="md">
      <Text>Title</Text>
    </Box>
  );
}

@headlessui/react often uses render props for complex state.

• Components like Menu expose state (like open) to children via functions.
• Allows you to conditionally style based on component state.
• Can lead to deeper nesting in JSX.

// headless: Render props for state
import { Menu, MenuButton, MenuItems } from '@headlessui/react';

function Nav() {
  return (
    <Menu>
      {({ open }) => (
        <>
          <MenuButton className={open ? 'active' : 'inactive'}>Open</MenuButton>
          <MenuItems>...</MenuItems>
        </>
      )}
    </Menu>
  );
}

react-accessible-accordion uses a fixed component structure.

• You must wrap content in specific components (Item, Button, Panel).
• Less flexible than render props but very predictable.
• Changing the DOM structure can break accessibility logic.

// accordion: Fixed structure
import { Accordion, AccordionItem, AccordionButton, AccordionPanel } from 'react-accessible-accordion';

function FAQ() {
  return (
    <Accordion>
      <AccordionItem>
        <AccordionButton>Title</AccordionButton>
        <AccordionPanel>Content</AccordionPanel>
      </AccordionItem>
    </Accordion>
  );
}

🛠️ Real-World Scenarios

Scenario 1: Internal Admin Dashboard

You need tables, forms, modals, and layouts quickly.

• ✅ Best choice: @chakra-ui/react
• Why? You get all components pre-styled and accessible. Speed is key.

// chakra: Rapid dashboard
import { Input, Button, Stack } from '@chakra-ui/react';

function LoginForm() {
  return (
    <Stack>
      <Input placeholder="Email" />
      <Button type="submit">Login</Button>
    </Stack>
  );
}

Scenario 2: Custom Brand Marketing Site

You have a strict design system built with Tailwind CSS.

• ✅ Best choice: @headlessui/react
• Why? You need the interaction logic without overriding default styles.

// headless: Tailwind integration
import { Disclosure } from '@headlessui/react';

function FAQ() {
  return (
    <Disclosure>
      <Disclosure.Button className="text-white">Question</Disclosure.Button>
      <Disclosure.Panel className="bg-gray-100">Answer</Disclosure.Panel>
    </Disclosure>
  );
}

Scenario 3: Simple Landing Page with FAQ

You only need one interactive section and want to keep dependencies low.

• ✅ Best choice: react-accessible-accordion
• Why? Installing a full library for one component is overkill.

// accordion: Lightweight
import { Accordion, AccordionItem, AccordionButton, AccordionPanel } from 'react-accessible-accordion';

function FAQ() {
  return (
    <Accordion>
      <AccordionItem>
        <AccordionButton>Details</AccordionButton>
        <AccordionPanel>Info</AccordionPanel>
      </AccordionItem>
    </Accordion>
  );
}

⚠️ Maintenance and Ecosystem

@chakra-ui/react is actively maintained with a large community.

• Regular updates and long-term support.
• V3 is in development with performance improvements.
• Safe for long-term enterprise projects.

@headlessui/react is maintained by Tailwind Labs.

• Tightly integrated with the Tailwind ecosystem.
• Very stable, as it solves a narrow set of problems well.
• Safe for production use.

react-accessible-accordion has slower update cycles.

• It is a specialized tool that may not see frequent feature updates.
• Check the repository for recent commits before adopting.
• Consider if @headlessui/react Disclosure component could replace it.

📌 Summary Table

💡 Final Recommendation

Think in terms of control vs. convenience:

• Need maximum convenience? → Go with @chakra-ui/react. It handles styling and a11y so you can focus on logic.
• Need maximum control? → Go with @headlessui/react. It handles a11y logic while you handle the visuals.
• Need just one component? → react-accessible-accordion works, but ensure it fits your long-term maintenance plan.

These tools all aim to make the web more accessible. Choose the one that fits your team's design workflow and performance requirements.