Svelte Accessibility: The Complete WCAG 2.2 Guide

The WCAG 2.2 Criteria Svelte Apps Break Most

For the full list, see the WCAG 2.2 Level AA requirements and the interactive WCAG 2.2 checklist.

2. Read the Compiler's a11y_* Warnings

This is Svelte's signature accessibility advantage. As the compiler analyzes your markup it emits warnings whose codes begin with a11y_ whenever it sees a likely accessibility bug. They print in your terminal during dev and build, and appear inline in your editor through the Svelte extension — so you find the problem while writing the component, not after an audit. No other mainstream framework checks accessibility at compile time.

Treat every a11y_ warning as a bug to fix, not noise to hide. Svelte lets you suppress a single line with a comment, but that comment is a promise that you have checked the case and it is genuinely a false positive:

<!-- Only after you have verified this specific case is safe.
     A suppressed warning is an accessibility defect you keep on purpose. -->
<!-- svelte-ignore a11y_no_static_element_interactions -->
<div role="presentation" on:click={dismiss}>...</div>

Run svelte-check in CI so these warnings fail the build instead of scrolling past in a log. The compiler only sees static markup, though — it cannot know whether your dialog traps focus or your toast is announced, which is what the rest of this guide covers. Every role and state the warnings mention is documented in our ARIA roles & attributes reference.

4. Package Focus Behavior as a use: Action

A Svelte action is a function you attach to an element with use:name. Svelte calls it with the real DOM node when the element mounts and runs the destroy() you return when it unmounts. That lifecycle makes actions the idiomatic Svelte home for accessibility behavior that needs a live element — a focus trap, click-outside-to-close, or moving focus on open. You write the logic once and reuse it with a single attribute.

// actions/trapFocus.ts — a reusable focus trap
export function trapFocus(node: HTMLElement) {
  const previouslyFocused = document.activeElement as HTMLElement | null

  const selector =
    'a[href], button:not([disabled]), input:not([disabled]), ' +
    'select, textarea, [tabindex]:not([tabindex="-1"])'
  const focusable = () =>
    Array.from(node.querySelectorAll<HTMLElement>(selector))

  // Move focus into the dialog when it opens
  focusable()[0]?.focus()

  function onKeydown(e: KeyboardEvent) {
    if (e.key !== "Tab") return
    const items = focusable()
    const first = items[0]
    const last = items[items.length - 1]
    if (e.shiftKey && document.activeElement === first) {
      last.focus()
      e.preventDefault()
    } else if (!e.shiftKey && document.activeElement === last) {
      first.focus()
      e.preventDefault()
    }
  }

  node.addEventListener("keydown", onKeydown)

  return {
    destroy() {
      node.removeEventListener("keydown", onKeydown)
      previouslyFocused?.focus() // restore focus to what opened the dialog
    },
  }
}

<script lang="ts">
  import { trapFocus } from "./actions/trapFocus"
  let open = $state(false)
</script>

<button type="button" on:click={() => (open = true)}>Delete project</button>

{#if open}
  <div class="backdrop" on:click={() => (open = false)}></div>
  <div
    role="dialog"
    aria-modal="true"
    aria-labelledby="dialog-title"
    use:trapFocus
    on:keydown={(e) => e.key === "Escape" && (open = false)}
  >
    <h2 id="dialog-title">Delete this project?</h2>
    <p>This action cannot be undone.</p>
    <button type="button" on:click={() => (open = false)}>Cancel</button>
    <button type="button" on:click={confirm}>Delete</button>
  </div>
{/if}

Because the action's destroy() runs the moment the {#if} removes the dialog, focus restoration is automatic — no lifecycle bookkeeping in the component. You still supply role="dialog", aria-modal="true", an accessible name via aria-labelledby, and Escape-to-close. For production dialogs, headless libraries such as Bits UI and Melt UI ship a fully accessible Dialog so you rarely hand-roll one. See the accessible modal pattern for the full interaction spec and the focus management guide for traps and restoration in depth.

6. Announce Dynamic Content (and the {#if} Trap)

Reactivity updates the DOM silently. When search results load, a toast appears, or a form saves, a sighted user sees it instantly — a screen reader user hears nothing unless the change happens inside an aria-live region. The catch is the same one every framework hits: a screen reader only announces a live region that already existed in the DOM before its content changed. Mount that region with {#if} at the moment the message appears and nothing is announced.

<!-- Broken: the region is created at the same moment as its text,
     so the browser treats it as initial content, not an update -->
{#if message}
  <p aria-live="polite">{message}</p>
{/if}

<!-- Correct: the region is always in the DOM; only its text changes -->
<p aria-live="polite" class="sr-only">{message}</p>

// lib/announcer.svelte.ts — one persistent region for the whole app
export const announcer = $state({ message: "" })

export function announce(text: string) {
  announcer.message = ""              // reset so identical messages re-announce
  requestAnimationFrame(() => {
    announcer.message = text
  })
}

Render one always-mounted, visually hidden region near the root of your layout (<p aria-live="polite" class="sr-only">{announcer.message}</p>) and call announce() from anywhere. Resetting the text before setting it again forces a re-announcement even when the new message is identical to the last. Reserve aria-live="assertive" for urgent, interrupting messages such as a session-timeout warning. This satisfies 4.1.3 Status Messages.

7. Accessible Forms with bind:value

bind:value handles the data binding, but says nothing about accessibility. Associate every input with a <label> (the compiler's a11y_label_has_associated_control warning enforces this), then link the error message with aria-describedby and mark the field with aria-invalid — binding undefined so the attributes disappear when the field is valid.

<script lang="ts">
  let email = $state("")
  let touched = $state(false)
  let invalid = $derived(touched && !/^[^@]+@[^@]+\.[^@]+$/.test(email))
</script>

<form on:submit|preventDefault={submit}>
  <label for="email">Email</label>
  <input
    id="email"
    type="email"
    bind:value={email}
    on:blur={() => (touched = true)}
    aria-invalid={invalid || undefined}
    aria-describedby={invalid ? "email-error" : undefined}
  />
  {#if invalid}
    <p id="email-error" class="error">Enter a valid email address.</p>
  {/if}

  <button type="submit">Create account</button>
</form>

Never rely on a placeholder as the label — it disappears on input and usually fails contrast. Only surface aria-invalid and aria-describedby once the user has touched the field (here, on blur), so assistive tech is not told about an error before it is shown. The error text sits inside a {#if} — that is fine, because aria-describedby resolves the id when it exists; it is only live regions that must stay mounted. For labels, <fieldset> grouping, validation timing, and error summaries, see the accessible forms guide and the form validation & error handling guide.

8. Testing & Tooling

Automated checks catch a meaningful share of issues and stop regressions — but they find roughly a third to a half of WCAG problems, so they supplement rather than replace manual testing. Svelte gives you an extra automated layer for free in the compiler; layer these into your workflow:

# 1. The compiler + svelte-check — a11y warnings fail the build
svelte-check --fail-on-warnings

# 2. Lint on top of the compiler — eslint-plugin-svelte
#    In eslint.config.js, extend the svelte recommended config.

// 3. Component tests: @testing-library/svelte + vitest-axe
import { render } from "@testing-library/svelte"
import { axe } from "vitest-axe"
import TextField from "./TextField.svelte"

it("TextField has no axe violations", async () => {
  const { container } = render(TextField, { props: { label: "Email", id: "email" } })
  expect(await axe(container)).toHaveNoViolations()
})

// 4. End-to-end: axe-core in Playwright against real routes
import AxeBuilder from "@axe-core/playwright"

test("home page is accessible", async ({ page }) => {
  await page.goto("/")
  const results = await new AxeBuilder({ page }).analyze()
  expect(results.violations).toEqual([])
})

Svelte Testing Library nudges you toward accessible queries — getByRole and getByLabelText only pass when the accessibility tree is correct, so writing tests this way surfaces missing names early. Finish every feature with a manual keyboard pass and a screen reader pass. Read our comparison of automated vs manual testing to see where each fits.

Svelte Accessibility Checklist

1. Zero a11y warnings. The build has no unresolved a11y_* warnings; svelte-check runs in CI and any svelte-ignore is documented.
2. Semantic markup. Every clickable thing is a <button> or <a href>; headings ordered; one <h1> per page.
3. Reactive ARIA. Dynamic ARIA uses {expression} bindings and undefined to remove attributes when off.
4. Focus behavior. Traps and restoration are packaged as use: actions; overlays move focus in and back out.
5. Route titles & focus. Every route sets a unique <svelte:head><title>; afterNavigate refines focus; a skip link exists.
6. Live regions. Async results and errors announce from an always-mounted aria-live region (not {#if}).
7. Forms. Labels associated; errors linked with aria-describedby and aria-invalid.
8. Automated + manual. Compiler + eslint-plugin-svelte + vitest-axe in CI, plus a keyboard and screen reader pass.

Scan the deployed build with our URL accessibility auditor and work through the full WCAG 2.2 checklist.