--- title: "Custom appearance streams for PDF annotations" canonical_url: "https://www.nutrient.io/guides/android/annotations/appearance-streams/" md_url: "https://www.nutrient.io/guides/android/annotations/appearance-streams.md" last_updated: "2026-05-18T06:34:32.137Z" description: "Learn how to set up appearance streams in PDF annotations on Android for tailored visual representations and improved user experience." --- # Enhance PDF annotation with custom appearance streams An annotation or form element in a PDF can specify an appearance stream, which allows the annotation to be rendered differently than its default annotation rendering. Each appearance stream is a self-contained PDF object that will be rendered inside the annotation rectangle. (See also: [What are appearance streams?](https://www.nutrient.io/blog/what-are-appearance-streams/)) Most appearance streams are _just a visual representation of an annotation’s properties_. This helps third-party PDF viewers that may be unable to directly generate a visual representation of those properties; these viewers can render the appearance stream instead. Appearance streams also ensure that the annotations in a document are displayed exactly as they were created in the source PDF editor, without subtle differences that could occur if the third-party PDF viewer had to recreate the annotations from raw annotation data. However, sometimes appearance streams contain surprises. For example, square annotations may have an appearance stream with a photograph. There are a lot of edge cases out there, so one cannot disable appearance stream rendering and assume the annotation will look the same or even close to it. If you’re using Document Engine, note that appearance stream rendering only works for documents uploaded after upgrading to 2020.3.0. Changing an annotation will remove existing appearance streams and rerender them using the Nutrient drawing engine. Some exceptions apply, such as stamp annotations containing an image or signature form elements. Nutrient allows you to set an appearance stream to any annotation by setting [`AppearanceStreamGenerator`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations.appearance/-appearance-stream-generator/index.html) for your [`Annotation`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/index.html)s via the [`setAppearanceStreamGenerator()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/appearance-stream-generator.html) method. ## Appearance stream generator We provide basic implementations of the [`AppearanceStreamGenerator`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations.appearance/-appearance-stream-generator/index.html) interface: - [`AssetAppearanceStreamGenerator`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations.appearance/-asset-appearance-stream-generator/index.html) generates an appearance stream from the first page of a PDF stored in your app’s assets. - [`ContentResolverAppearanceStreamGenerator`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations.appearance/-content-resolver-appearance-stream-generator/index.html) generates an appearance stream from the first page of a PDF stored in Android’s [`ContentProvider`](https://developer.android.com/reference/android/content/ContentProvider). Setting an appearance stream generator does not automatically remove the existing appearance stream. The appearance stream only gets generated when the annotation has been modified or when calling [`generateAppearanceStream()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/generate-appearance-stream.html) on [`Annotation`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation/index.html) explicitly. ## Annotation with an appearance stream generator It’s easy to set up an annotation to show a custom appearance stream. This is typically done with stamp annotations because they have few other properties. A stamp annotation used this way is usually called an image annotation. To learn more, see our guide on [image annotations](https://www.nutrient.io/../../annotations/image-annotations/). ## Global appearance stream generators Custom appearance streams generated via [`AppearanceStreamGenerator`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations.appearance/-appearance-stream-generator/index.html) are saved into a document when saving. However, appearance streams need to be regenerated whenever annotations are modified after the document is reloaded. It can be inconvenient to set appearance stream generators for all annotations that need to have custom appearances. A cleaner approach is to add global appearance stream generators via [`addAppearanceStreamGenerator()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation-provider/add-appearance-stream-generator.html) on [`AnnotationProvider`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations/-annotation-provider/index.html). Global appearance stream generators added via this method have a chance to override appearance stream generation for all annotations in the document. Your custom appearance stream generator will be asked if it wishes to generate an annotation’s appearance stream via [`shouldUseGeneratorForAnnotation()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations.appearance/-appearance-stream-generator/should-use-generator-for-annotation.html). When `true`, you are expected to return a [`DataProvider`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document.providers/-data-provider/index.html) instance to a PDF that should be used as the annotation’s appearance stream when [`getDataProviderForAnnotation()`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.annotations.appearance/-appearance-stream-generator/get-data-provider-for-annotation.html) is called. Syncing appearance streams is currently not supported by Nutrient Instant. --- ## Related pages - [Hiding annotations on Android](/guides/android/annotations/configuring-editablevisible-annotation-types.md) - [Configure PDF annotations in Android](/guides/android/annotations/annotation-configuration.md) - [Store custom data in annotations on Android](/guides/android/annotations/custom-data-in-annotations.md) - [JavaScript support in annotations on Android](/guides/android/miscellaneous/javascript-api.md) - [Customizing the note icon on Android](/guides/android/annotations/customize-annotation-rendering.md)