FAQ Accordion Component

One of the biggest mistakes in FAQ accordion projects is making the question row clickable with a <div> or <p> element. It may work with a mouse, but it usually fails for keyboard users and does not communicate proper interactive meaning to assistive technologies.

Problematic approach:

          <div class="faq-question">
              What is frontend development?
          </div>

This element is not naturally focusable, does not respond to Enter or Space by default, and does not clearly describe itself as a control.

Better approach:

          <button class="faq-question" type="button" aria-expanded="false" aria-controls="answer-1">
          What is frontend development?
          </button>

          <div class="faq-answer" id="answer-1" hidden>
            Frontend development focuses on building the user-facing part of websites and applications.
          </div>
        

Pay attention to: Use a real <button> for every accordion trigger. Buttons are keyboard-accessible by default, communicate interactivity correctly, and make the JavaScript logic simpler. If you use <details> and <summary>, they also provide built-in disclosure behavior, but custom accordions should still use proper controls.

Beginners often toggle only CSS classes, so the accordion visually opens and closes, but assistive technologies do not receive accurate state information. This creates a mismatch between what sighted users see and what screen reader users hear.

Incomplete JavaScript:

          button.addEventListener('click', () => {
            answer.classList.toggle('is-open');
          });

This changes the layout visually, but the button still does not announce whether the related answer is expanded or collapsed.

Accessible state update:

          button.addEventListener('click', () => {
            const isOpen = button.getAttribute('aria-expanded') === 'true';

            button.setAttribute('aria-expanded', String(!isOpen));
            answer.hidden = isOpen;
          });

Pay attention to: Every visual state change should have a matching semantic state change. If an answer is visible, the trigger should have aria-expanded="true". If the answer is hidden, the trigger should return to aria-expanded="false".

Smooth accordion animation is a common requirement, but many beginners try to animate directly from height: 0 to height: auto. CSS cannot transition to or from auto reliably, so the animation either does not run or behaves inconsistently.

Problematic CSS:

          .faq-answer {
            height: 0;
            overflow: hidden;
            transition: height 0.3s ease;
          }

          .faq-answer.is-open {
            height: auto;
          }

This looks logical, but height: auto is not a numeric value that CSS can interpolate smoothly.

Simpler beginner-friendly solution:

          .faq-answer {
            max-height: 0;
            overflow: hidden;
            opacity: 0;
            transition: max-height 0.3s ease, opacity 0.2s ease;
          }

          .faq-answer.is-open {
            max-height: 300px;
            opacity: 1;
          }

More flexible JavaScript-assisted solution:

          function openAnswer(answer) {
            answer.hidden = false;
            answer.style.maxHeight = answer.scrollHeight + 'px';
          }

          function closeAnswer(answer) {
            answer.style.maxHeight = '0px';

            answer.addEventListener('transitionend', () => {
              answer.hidden = true;
              }, { once: true });
          }

Pay attention to: If FAQ answers can have very different lengths, avoid tiny fixed max-height values. Use scrollHeight when you need a more reliable animation, and always test both short and long answers.

Accordion behavior should be intentional. Some accordions allow multiple answers open at the same time, while others allow only one open item. A common beginner mistake is mixing both behaviors accidentally, which creates confusing UI logic and hard-to-debug code.

Unclear toggle logic:

          buttons.forEach((button) => {
           button.addEventListener('click', () => {
              button.classList.toggle('active');
                button.nextElementSibling.classList.toggle('open');
              });
          });

This works for simple toggling, but it does not define whether other answers should close. As the component grows, this ambiguity can create inconsistent behavior.

Clear one-open-at-a-time logic:

          buttons.forEach((button) => {
            button.addEventListener('click', () => {
              const shouldOpen = button.getAttribute('aria-expanded') !== 'true';

              buttons.forEach((item) => {
                const panel = document.getElementById(item.getAttribute('aria-controls'));
                item.setAttribute('aria-expanded', 'false');
                panel.hidden = true;
              });

              if (shouldOpen) {
                const panel = document.getElementById(button.getAttribute('aria-controls'));
                button.setAttribute('aria-expanded', 'true');
                panel.hidden = false;
              }
            });
          });

Pay attention to: Decide the behavior before writing JavaScript. If the accordion is used for compact FAQ reading, one-open-at-a-time behavior can reduce visual clutter. If users need to compare several answers, allowing multiple open panels may be better.

Another common issue is hiding the answer visually while leaving it available to keyboard users and screen readers. For example, using only opacity: 0 makes content invisible, but it may still occupy space or remain reachable depending on the rest of the CSS.

Problematic CSS-only hiding:

            .faq-answer {
              opacity: 0;
            }

            .faq-answer.is-open {
              opacity: 1;
            }

This does not properly remove the hidden answer from the interaction flow.

Better approach with hidden attribute:

            <button type="button" aria-expanded="false" aria-controls="answer-2">
              Can I use only HTML and CSS?
            </button>

            <div id="answer-2" class="faq-answer" hidden>
              Yes, simple accordions can be built with details and summary.
            </div>

JavaScript update:

            function togglePanel(button) {
              const panel = document.getElementById(button.getAttribute('aria-controls'));
              const isOpen = button.getAttribute('aria-expanded') === 'true';

              button.setAttribute('aria-expanded', String(!isOpen));
              panel.hidden = isOpen;
            }

Pay attention to: Hidden content should be hidden both visually and semantically. Use the hidden attribute, proper ARIA states, or carefully managed CSS classes that do not leave closed content accidentally accessible.

FAQ accordions are often placed on support pages, documentation pages, and product pages where users may rely on keyboard navigation. If focus styles are removed or never designed, users can tab through the accordion without knowing which question is currently active.

Problematic reset:

button {
            outline: none;
          }

Removing outlines without replacing them creates an accessibility problem and makes the component harder to use.

Better focus styling:

.faq-question:focus-visible {
              outline: 3px solid #2fc969;
              outline-offset: 4px;
            }

            .faq-question:hover {
              color: #14856e;
            }

Pay attention to: Test the component without a mouse. Press Tab to move between questions, Enter or Space to open an answer, and Shift + Tab to move backward. If you cannot clearly see where focus is, the component is not finished.