Update PDF annotation properties in Flutter

This guide shows you how to update PDF annotation properties in Flutter while preserving annotation metadata.

How it works

Use the annotation properties API to update annotations without replacing their metadata:

Retrieve annotation properties with getAnnotationProperties().
Update properties with immutable withX() methods.
Save changes with saveAnnotationProperties().
Persist changes to the document.

Basic usage

The following example updates an annotation’s color, opacity, and line width:

// Get annotation properties.
final properties = await controller.document.annotations.getAnnotationProperties(pageIndex, annotationId);

// Update properties (chain multiple updates).
final updated = properties
    ?.withColor(Colors.red)
    .withOpacity(0.7)
    .withLineWidth(3.0);

// Save changes.
if (updated != null) {
  await controller.document.annotations.saveAnnotationProperties(updated);
}

Common operations

The following examples show common ways to modify annotation properties, such as color, opacity, and flags.

Update color

final updated = properties?.withColor(Colors.blue);
await controller.document.annotations.saveAnnotationProperties(updated);

Update opacity

final updated = properties?.withOpacity(0.5); // 0.0 to 1.0
await controller.document.annotations.saveAnnotationProperties(updated);

Update line width

final updated = properties?.withLineWidth(2.5);
await controller.document.annotations.saveAnnotationProperties(updated);

Toggle flags

final flags = properties?.flagsSet ?? {};
final newFlags = Set<AnnotationFlag>.from(flags);
newFlags.contains(AnnotationFlag.readOnly)
    ? newFlags.remove(AnnotationFlag.readOnly)
    : newFlags.add(AnnotationFlag.readOnly);

final updated = properties?.withFlags(newFlags);
await controller.document.annotations.saveAnnotationProperties(updated);

Update custom data

final data = {
  ...(properties?.customData ?? {}),
  'key': 'value',
};

final updated = properties?.withCustomData(data);
await controller.document.annotations.saveAnnotationProperties(updated);

Available methods

The annotation properties API provides these immutable update methods:

Method	Parameter	Description
`withColor()`	`Color`	Update color
`withOpacity()`	`double`	Update opacity (0.0–1.0)
`withLineWidth()`	`double`	Update line width
`withFlags()`	`Set<AnnotationFlag>`	Update flags
`withCustomData()`	`Map<String, String>`	Update custom data
`withBoundingBox()`	`Rect`	Update position/size
`withContents()`	`String`	Update text content
`withSubject()`	`String`	Update subject

Common flags

Use annotation flags to control visibility, printing, and editing behavior:

AnnotationFlag.hidden        // Hidden from view.
AnnotationFlag.print         // Printable.
AnnotationFlag.readOnly      // No user interaction.
AnnotationFlag.locked        // Cannot delete/modify.
AnnotationFlag.lockedContents // Contents locked.

Use selection events

You can update annotation properties in response to annotation selection events:

controller.events.annotationSelected.listen((event) async {
  for (final annotation in event.annotations) {
    final annotationId = annotation.id ?? annotation.name;
    if (annotationId == null) continue;

    final properties = await controller.document.annotations
        .getAnnotationProperties(annotation.pageIndex, annotationId);

    final updated = properties?.withColor(Colors.red);
    if (updated != null) {
      await controller.document.annotations.saveAnnotationProperties(updated);
    }
  }
});

Migrate from the deprecated API

Migrate from the deprecated annotation update API to the properties-based approach to retain metadata.

Old:

final annotation = await document.getAnnotation(pageIndex, annotationId);
await document.updateAnnotation(annotation.copyWith(color: Colors.red));
// Loses metadata.

New:

final properties = await controller.document.annotations.getAnnotationProperties(pageIndex, annotationId);
final updated = properties?.withColor(Colors.red);
if (updated != null) {
  await controller.document.annotations.saveAnnotationProperties(updated);
}
// Preserves all data.