--- title: "Flutter SDK 4.2 migration guide" canonical_url: "https://www.nutrient.io/guides/flutter/migration-guides/flutter-4-2-migration-guide/" md_url: "https://www.nutrient.io/guides/flutter/migration-guides/flutter-4-2-migration-guide.md" last_updated: "2026-06-08T17:11:05.525Z" description: "Follow this guide to update your project for Nutrient Flutter SDK 4.2 with essential changes and API updates." --- # Flutter SDK 4.2 migration guide Nutrient Flutter SDK 4.2 introduces significant improvements to annotation handling with the introduction of Dart model classes, providing a more type-safe and intuitive way to work with annotations. This guide will help you migrate your existing code to take advantage of these new capabilities. ## Updating to Nutrient Flutter SDK 4.2 To update your project to Nutrient Flutter SDK 4.2, update your `pubspec.yaml` file: ```yaml dependencies: pspdfkit_flutter: ^4.2.0 ``` Run `flutter pub get` to install the latest version. ## Annotation model classes The most significant change in version 4.2 is the introduction of Dart model classes for annotations. These classes replace the previous JSON-based approach and provide a more structured way to work with annotations. ### Key benefits - **Type safety** — Model classes provide type checking at compile time, reducing runtime errors. - **Better IDE support** — Enjoy code completion and documentation for annotation properties. - **Simplified API** — Work with annotations using native Dart objects instead of raw JSON. - **Serialization support** — All annotation model classes can be serialized to and deserialized from JSON. ## API changes Read the following sections to learn more about API changes in Nutrient Flutter SDK 4.2. ### Annotation methods This section details which annotation methods were changed. #### addAnnotation and removeAnnotation The `addAnnotation` and `removeAnnotation` methods now accept both model classes and plain JSON, providing backward compatibility, while encouraging migration to model classes. **Before:** ```dart // Using JSON only. await pdfDocument.addAnnotation({ 'type': 'pspdfkit/ink', 'bbox': [89.0, 98.0, 143.0, 207.0], 'lines': [[[92.0, 159.0], [95.0, 155.0]]], 'pageIndex': 0 }); ``` **After:** ```dart // Using model class. // Create an ink annotation with drawing points. final inkAnnotation = InkAnnotation( id: 'ink-annotation-1', bbox: [267.4, 335.1, 97.2, 10.3], createdAt: '2025-01-06T16:36:59+03:00', lines: InkLines( points: [ [ [269.4, 343.4], [308.4, 341.7], [341.2, 339.6], [358.8, 339.6], [360.9, 339.2], [362.6, 338.8], [361.7, 337.1], ] ], intensities: [ [1.0, 0.43, 0.64, 0.83, 0.98, 0.99, 0.97] ], ), pageIndex: 0 //...other fields. ); await pdfDocument.addAnnotation(inkAnnotation); // Still supports JSON for backward compatibility. await pdfDocument.addAnnotation({ 'type': 'pspdfkit/ink', 'bbox': [89.0, 98.0, 143.0, 207.0], 'lines': [[[92.0, 159.0], [95.0, 155.0]]], 'pageIndex': 0 //...other fields }); ``` A new method has been added to simplify updating existing annotations: ```dart // Get an annotation. final annotations = await pdfDocument.getAnnotations(pageIndex: 0); final annotation = annotations.first; // Modify it. if (annotation is InkAnnotation) { annotation.copyWith( strokeColor: Color.red ) } // Update it. await pdfDocument.updateAnnotation(annotation); ``` #### getAnnotations The `getAnnotations` method now returns a list of model classes instead of JSON objects. **Before:** ```dart final annotations = await pdfDocument.getAnnotations( 0, "all"); // annotations is List> final type = annotations[0]['type']; ``` **After:** ```dart var pageIndex = 0; final annotations = await pdfDocument.getAnnotations(pageIndex, AnnotationType.all); // annotations is List final type = annotations[0].type; // You can use type checking. if (annotations[0] is InkAnnotation) { final inkAnnotation = annotations[0] as InkAnnotation; final lines = inkAnnotation.lines; } ``` #### getUnsavedAnnotations The `getUnsavedAnnotations` method now returns a list of model classes instead of JSON objects. **To get annotations as JSON** If you still need to work with JSON representations, use the following code: ```dart // Get annotations as model classes. final annotations = await pdfDocument.getAnnotations(pageIndex: 0); // Get annotations as JSON. final annotationsJson = await pdfDocument.getAnnotationsAsJSON(pageIndex: 0); ``` #### getAllUnsavedAnnotations The `getAllUnsavedAnnotations` method has been deprecated in favor of `getUnsavedAnnotations`. It still works, but it’ll be removed in a future release. ### Event listeners Annotation-related event listeners now use model classes instead of plain JSON. **Before:** ```dart pdfDocument.addEventListener(PdfDocumentEvent.annotationChanged, (data) { final annotationJson = data['annotation']; print('Annotation changed: ${annotationJson['type']}'); }); ``` **After:** ```dart pdfDocument.addEventListener(PdfDocumentEvent.annotationChanged, (data) { final annotation = data['annotation'] as Annotation; print('Annotation changed: ${annotation.type}'); // Type checking. if (annotation is InkAnnotation) { print('Ink annotation lines: ${annotation.lines}'); } }); ``` ## Migrating step by step 1. **Update your pubspec.yaml** to use version 4.2.0 or later. 2. **Import the new model classes** where you work with annotations. 3. **Update your code** to use model classes instead of JSON objects. 4. **Test your application** thoroughly, especially annotation-related functionality. ## Backward compatibility To ease migration, many methods accept both model classes and JSON objects. However, we recommend transitioning to model classes for better type safety and code maintainability. ## Changelog For a complete list of changes in Nutrient Flutter SDK 4.2, see the [changelog](https://www.nutrient.io/guides/flutter/changelog.md). --- ## Related pages - [Flutter 1 10 4 Migration Guide](/guides/flutter/migration-guides/flutter-1-10-4-migration-guide.md) - [Flutter 3 3 Migration Guide](/guides/flutter/migration-guides/flutter-3-3-migration-guide.md) - [Flutter SDK 3 migration guide](/guides/flutter/migration-guides/flutter-3-migration-guide.md) - [Flutter 3 12 Migration Guide](/guides/flutter/migration-guides/flutter-3-12-migration-guide.md) - [Flutter 3 6 Migration Guide](/guides/flutter/migration-guides/flutter-3-6-migration-guide.md) - [Flutter 3 2 Migration Guide](/guides/flutter/migration-guides/flutter-3-2-migration-guide.md) - [Flutter 3 9 Migration Guide](/guides/flutter/migration-guides/flutter-3-9-migration-guide.md) - [Flutter SDK 4 migration guide](/guides/flutter/migration-guides/flutter-4-migration-guide.md) - [Download and run the migration script.](/guides/flutter/migration-guides/flutter-5-migration-guide.md) - [Upgrade to the latest Flutter version](/guides/flutter/migration-guides/upgrading.md)