← Flutter / Dart

Flutter / Dart · 23 / 24

Accessible Flutter forms

Verify labels, target sizes and enlarged text rendering.

  • Large
  • Advanced
  • 90 min

Prerequisites: Validate forms and navigate between screens, Unit and widget tests with meaningful expectations

In this tutorial
  1. Define the boundary
  2. Set up the learning project
  3. Trace the successful outcome
  4. Observe failures deliberately
  5. Solve the extension
  6. Compare the solution
  7. Exercise and solution
  8. Project context and sources

Download learning package

Setup and verification

Flutter 3.41.5 or newer with Dart 3.11. 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.

Verified on 2026-10-20 on Linux x86_64. Widget tests inspect semantics and layout at increased text size. A manual TalkBack or VoiceOver session is still required. A semantics check does not simulate a complete screen reader.

Accessibility combines several verifiable properties. An input needs a meaningful label, an action enough space and a form a visible error message. Fixed screen height may clip enlarged text. This example therefore uses a scrollable layout and wrapping text. Automated checks complement a real screen-reader walkthrough.

Package contents and individual files

01Define the boundary

A form needs identifiable labels, understandable errors and a logical reading order. Semantics exposes meaning to assistive technology. Flexible sizing and scrolling prevent clipped inputs at large text sizes.

lib/model.dart · dartOpen file
import 'package:flutter/material.dart';

class VehicleForm extends StatefulWidget {
  const VehicleForm({super.key});
  @override
  State<VehicleForm> createState() => _VehicleFormState();
}

class _VehicleFormState extends State<VehicleForm> {
  final controller = TextEditingController();
  String message = '';
  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => Scaffold(
    appBar: AppBar(title: const Text('Vehicle record')),
    body: SingleChildScrollView(
      padding: const EdgeInsets.all(24),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          TextField(
            controller: controller,
            decoration: const InputDecoration(labelText: 'Vehicle name'),
          ),
          const SizedBox(height: 24),
          FilledButton(
            onPressed: () => setState(
              () => message = controller.text.trim().isEmpty
                  ? 'Name required'
                  : 'Saved',
            ),
            child: const Text('Save vehicle'),
          ),
          Semantics(liveRegion: true, child: Text(message)),
        ],
      ),
    ),
  );
}

02Set up the learning project

Direct dependencies are pinned. Extract all files together and run flutter pub get. Do not use an existing app database for tests. Tests create and clean up their own data.

pubspec.yaml · yamlOpen file
name: learning_example
publish_to: none
environment:
  sdk: ">=3.11.0 <4.0.0"
dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: 3.3.1
  drift: 2.33.0
  path_provider: 2.1.5
dev_dependencies:
  flutter_test:
    sdk: flutter
flutter:
  uses-material-design: true

03Trace the successful outcome

Widget tests inspect semantics and layout at increased text size. A manual TalkBack or VoiceOver session is still required. A semantics check does not simulate a complete screen reader.

test/model_test.dart · dartOpen file
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:learning_example/model.dart';

void main() {
  testWidgets('large text, labelled targets and validation', (tester) async {
    final semantics = tester.ensureSemantics();
    await tester.pumpWidget(
      MaterialApp(
        builder: (context, child) => MediaQuery(
          data: MediaQuery.of(
            context,
          ).copyWith(textScaler: const TextScaler.linear(2)),
          child: child!,
        ),
        home: const VehicleForm(),
      ),
    );
    await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
    await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
    await tester.tap(find.text('Save vehicle'));
    await tester.pump();
    expect(find.text('Name required'), findsOneWidget);
    await tester.enterText(find.byType(TextField), 'Family car');
    await tester.tap(find.text('Save vehicle'));
    await tester.pump();
    expect(find.text('Saved'), findsOneWidget);
    expect(tester.takeException(), isNull);
    semantics.dispose();
  });
}

Run / check

flutter pub get
flutter test
Expected result

Widget tests inspect semantics and layout at increased text size. A manual TalkBack or VoiceOver session is still required. A semantics check does not simulate a complete screen reader.

04Observe failures deliberately

Change an expected number or state in the test. flutter test must fail. Restore the correct expectation afterwards. Distinguish a domain failure from a missing plugin or development environment.

05Solve the extension

Also verify the interface at triple text size and a narrow viewport.

06Compare the solution

The solution test sets logical width to 320 pixels and scrolls the action into view before tapping. This verifies visible and operable behaviour. TalkBack and VoiceOver still need separate device checks.

Expected result

flutter test passes for the original example and the extended solution.

Your exercise

Also verify the interface at triple text size and a narrow viewport.

Show the solution and explanation

The solution test sets logical width to 320 pixels and scrolls the action into view before tapping. This verifies visible and operable behaviour. TalkBack and VoiceOver still need separate device checks.

solution/model_test.dart · dartOpen file
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:learning_example/model.dart';

void main() {
  testWidgets('large text, labelled targets and validation', (tester) async {
    tester.view.physicalSize = const Size(320, 700);
    tester.view.devicePixelRatio = 1;
    addTearDown(tester.view.resetPhysicalSize);
    addTearDown(tester.view.resetDevicePixelRatio);
    final semantics = tester.ensureSemantics();
    await tester.pumpWidget(
      MaterialApp(
        builder: (context, child) => MediaQuery(
          data: MediaQuery.of(
            context,
          ).copyWith(textScaler: const TextScaler.linear(3)),
          child: child!,
        ),
        home: const VehicleForm(),
      ),
    );
    await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
    await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
    await tester.ensureVisible(find.text('Save vehicle'));
    await tester.tap(find.text('Save vehicle'));
    await tester.pump();
    expect(find.text('Name required'), findsOneWidget);
    await tester.enterText(find.byType(TextField), 'Family car');
    await tester.ensureVisible(find.text('Save vehicle'));
    await tester.tap(find.text('Save vehicle'));
    await tester.pump();
    expect(find.text('Saved'), findsOneWidget);
    expect(tester.takeException(), isNull);
    semantics.dispose();
  });
}

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.