How can I build a show-and-hide disclosure button that stays in sync?

Treat the button and the content it controls as two parts of one disclosure. The button’s aria-expanded value should be true when the content is visible and false when it is hidden. The WAI-ARIA Authoring Practices Guide describes the pattern as a button controlling a section, and says to keep the reported state consistent with actual visibility whenever visibility changes. aria-controls can identify the controlled section. [S1]

A practical rule is: do not update only the visual content or only the accessibility state. Route every change through the same small update function so both are set together.

Here is a plain HTML-and-JavaScript pattern. The example assumes this disclosure starts closed; adjust the initial values together if your page should start open.

<button type="button" id="details-button"
        aria-expanded="false" aria-controls="details-panel">
  Show details
</button>
<div id="details-panel" hidden>
  Extra information goes here.
</div>

<script>
  const button = document.querySelector('#details-button');
  const panel = document.querySelector('#details-panel');

  function setOpen(open) {
    panel.hidden = !open;
    button.setAttribute('aria-expanded', String(open));
    button.textContent = open ? 'Hide details' : 'Show details';
  }

  button.addEventListener('click', () => {
    setOpen(button.getAttribute('aria-expanded') !== 'true');
  });
</script>

The hidden property controls whether the panel is shown in this example; the same setOpen function updates aria-expanded and the button label. The label is useful visual wording, but it is not a replacement for the expanded state. The pattern guidance establishes the expected relationship and interaction, not a required framework or this particular code structure. [S1]

Changing the text inside an already-open panel does not by itself require changing whether the panel is expanded. The important case is when other code changes its visibility. If a reset closes the panel, have the reset call setOpen(false); if another action opens it, call setOpen(true). Avoid separately changing panel.hidden or aria-expanded in those other code paths.

For a larger component, keep one state value such as isOpen and have one render or update function derive both the visible panel and the button’s expanded state from it. This makes the state relationship explicit. The source guidance says the reported state should remain consistent whenever visibility changes, but it does not prescribe a particular state-management system. [S1]

Test the behavior, not just the appearance. Click the button to open and close the panel, and after each action check that the panel’s actual visibility agrees with aria-expanded. Then activate the button with Enter and Space; both are expected to toggle a disclosure button. [S1]

Also test any other path that can change visibility, such as a reset or a parent component update. If one path changes the panel without updating the button state, fix that path to use the shared update function. The guide describes the expected interaction and semantics; it does not establish that a particular sample is correct for every framework or page, so test your own implementation.