← React / TypeScript

React / TypeScript · 22 / 24

Accessible forms and dialogs

Verify focus, error feedback and return to the trigger in a real browser.

  • Large
  • Advanced
  • 90 min

Prerequisites: HTML and CSS: the foundation of a web interface, First React app: JSX, props and state, Test components and repositories meaningfully

In this tutorial
  1. Understand the state model
  2. Start the project
  3. Verify the contract with a test
  4. Observe failures and boundaries
  5. Implement the exercise
  6. Verify the solution
  7. Exercise and solution
  8. Project context and sources

Download learning package

Setup and verification

Node.js 22.23 or newer with npm. Python 3 is also required for the common verification entry point. Extract the learning package into a new folder and run python3 run_checks.py there. The script copies the included files into a temporary learning directory. It verifies the example and then the supplied solution there, preserving the original files. Required packages are downloaded on the first run.

Playwright downloads Chromium. A fresh Linux system may also require browser system libraries. The launcher reports missing libraries explicitly.

Verified on 2026-10-20 on Linux x86_64. Playwright operates the dialog by keyboard. Check opening, entry, Escape and restored focus. The exercise adds another dismissal path with the same focus guarantee.

A dialog interrupts the normal interaction flow. Its name, initial focus and return path must be clear. Native dialog provides modal behaviour. The application connects label, input and error feedback. A browser test verifies Escape and focus position.

Package contents and individual files

01Understand the state model

A modal dialog needs an accessible name, controlled focus and a return path. The native dialog element provides modality. The application chooses focus when opening and after closing.

src/App.tsx · typescriptOpen file
import { useRef, useState } from "react";
export default function App() {
  const dialog = useRef<HTMLDialogElement>(null);
  const trigger = useRef<HTMLButtonElement>(null);
  const [error, setError] = useState("");
  const [saved, setSaved] = useState("");
  return (
    <main>
      <h1>Vehicle records</h1>
      <button
        ref={trigger}
        onClick={() => {
          setError("");
          dialog.current?.showModal();
        }}
      >
        Add vehicle
      </button>
      <p role="status">{saved}</p>
      <dialog
        ref={dialog}
        aria-labelledby="dialog-title"
        onClose={() => trigger.current?.focus()}
      >
        <h2 id="dialog-title">New vehicle</h2>
        <form
          onSubmit={(e) => {
            e.preventDefault();
            const data = new FormData(e.currentTarget);
            const name = String(data.get("name") ?? "").trim();
            if (!name) {
              setError("Name required");
              return;
            }
            setSaved(name);
            dialog.current?.close();
          }}
        >
          <label htmlFor="name">Vehicle name</label>
          <input
            autoFocus
            id="name"
            name="name"
            aria-invalid={!!error}
            aria-describedby={error ? "error" : undefined}
          />
          <p id="error" role="alert">
            {error}
          </p>
          <button>Save</button>
          <button type="button" onClick={() => dialog.current?.close()}>
            Cancel
          </button>
        </form>
      </dialog>
    </main>
  );
}

02Start the project

Install the pinned dependencies and run npm run dev. Data consists of synthetic learning values. Open the local address and trigger the action yourself.

package.json · jsonOpen file
{
  "name": "appfabrik-learning",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "tsc --noEmit && vite build",
    "test": "playwright test"
  },
  "dependencies": {
    "react": "19.2.3",
    "react-dom": "19.2.3",
    "react-router-dom": "7.18.4",
    "@tanstack/react-query": "5.104.5"
  },
  "devDependencies": {
    "vite": "8.1.5",
    "typescript": "6.0.3",
    "@types/react": "19.2.14",
    "@types/react-dom": "19.2.3",
    "@types/node": "22.19.15",
    "vitest": "4.1.10",
    "@testing-library/react": "16.3.2",
    "@testing-library/user-event": "14.6.1",
    "jsdom": "29.1.1",
    "@playwright/test": "1.64.1"
  }
}

03Verify the contract with a test

Playwright operates the dialog by keyboard. Check opening, entry, Escape and restored focus. The exercise adds another dismissal path with the same focus guarantee.

tests/workflow.spec.ts · typescriptOpen file
import { test, expect } from "@playwright/test";
test("dialog validates and restores focus", async ({ page }) => {
  await page.goto("/");
  const trigger = page.getByRole("button", { name: "Add vehicle" });
  await trigger.click();
  await expect(page.getByRole("dialog", { name: "New vehicle" })).toBeVisible();
  await expect(page.getByLabel("Vehicle name")).toBeFocused();
  await page.getByRole("button", { name: "Save", exact: true }).click();
  await expect(page.getByRole("alert")).toHaveText("Name required");
  await page.keyboard.press("Escape");
  await expect(trigger).toBeFocused();
  await trigger.click();
  await page.getByLabel("Vehicle name").fill("Family car");
  await page.getByRole("button", { name: "Save", exact: true }).click();
  await expect(page.getByRole("status")).toHaveText("Family car");
  await expect(trigger).toBeFocused();
});

Run / check

npm install
npm test
npm run build
Expected result

Playwright operates the dialog by keyboard. Check opening, entry, Escape and restored focus. The exercise adds another dismissal path with the same focus guarantee.

04Observe failures and boundaries

Change the expected output and observe a failed test. A TypeScript build protects type contracts while a browser test protects interactions. The two checks serve different purposes.

05Implement the exercise

Also verify Cancel and ensure no data is committed.

06Verify the solution

The solution enters a draft, cancels and checks both unchanged confirmed state and restored focus. A closed dialog alone would not be sufficient evidence. Copy the solution files to the corresponding locations in the learning project and run tests and build again.

Expected result

Tests and type checking pass. The observed result matches the learning goal.

Your exercise

Also verify Cancel and ensure no data is committed.

Show the solution and explanation

The solution enters a draft, cancels and checks both unchanged confirmed state and restored focus. A closed dialog alone would not be sufficient evidence.

solution/workflow.spec.ts · typescriptOpen file
import { test, expect } from "@playwright/test";
test("dialog validates and restores focus", async ({ page }) => {
  await page.goto("/");
  const trigger = page.getByRole("button", { name: "Add vehicle" });
  await trigger.click();
  await expect(page.getByRole("dialog", { name: "New vehicle" })).toBeVisible();
  await expect(page.getByLabel("Vehicle name")).toBeFocused();
  await page.getByRole("button", { name: "Save", exact: true }).click();
  await expect(page.getByRole("alert")).toHaveText("Name required");
  await page.keyboard.press("Escape");
  await expect(trigger).toBeFocused();
  await trigger.click();
  await page.getByLabel("Vehicle name").fill("Family car");
  await page.getByRole("button", { name: "Save", exact: true }).click();
  await expect(page.getByRole("status")).toHaveText("Family car");
  await expect(trigger).toBeFocused();
});

test("cancel preserves confirmed state", async ({ page }) => {
  await page.goto("/");
  await page.getByRole("button", { name: "Add vehicle" }).click();
  await page.getByLabel("Vehicle name").fill("Draft");
  await page.getByRole("button", { name: "Cancel", exact: true }).click();
  await expect(page.getByRole("status")).toBeEmpty();
  await expect(page.getByRole("button", { name: "Add vehicle" })).toBeFocused();
});

Project context and sources

This independent learning project explores a topic in this technology area. Project references provide a pinned revision as architectural context. They do not imply that every library or feature introduced here is already used in that application.