1.26 release notes
RSSNutrient Web SDK 1.26 adds an option to draw form fields and annotations in the order the document lists them. It also adds the sync.refused event, which reports changes that Document Engine permanently refuses.
This release also includes these changes:
- Toolbar color buttons include the selected color in their accessible name.
- The SDK bundles React 19.
For a complete list of changes and fixes, refer to the changelog.
Form fields and annotations in document order
By default, the SDK draws form fields above annotations such as shapes, ink, stamps, and notes. An annotation placed over a form field appears below it.
To draw form fields and annotations in the order the document lists them, set forceRenderWidgetsInAnnotationsOrder to true in the view state:
NutrientViewer.load({ initialViewState: new NutrientViewer.ViewState({ forceRenderWidgetsInAnnotationsOrder: true, }),});The SDK then draws each annotation above the form fields that precede it in the document, and the annotation receives clicks where they overlap. New annotations and form fields come last, so they appear on top.
The following limits apply:
- Text markup annotations, such as highlights and underlines, stay below all other annotations. Links, ink signatures, and image signatures stay on top.
- The tab order doesn’t change. When an annotation completely covers a form field, users can reach the field only with the keyboard. The field appears on top while it has focus.
- Changing the tab order with
instance.setPageTabOrder()can also change the drawing order, because it reorders the page’s annotation list. - A comparator set with
instance.setAnnotationRenderingOrderComparator()takes precedence over the option, and form fields stay on top.
In server-backed mode, the following also applies:
- Annotations from an uploaded PDF retain document order only with Document Engine 1.21.0 or later, which isn’t released yet. With an older version, they stay below form fields, and new annotations still appear on top.
- With Document Engine 1.21.0 or later, editing an annotation or form field from the uploaded PDF moves it to the top on the next load. Image annotations, stamp annotations, and form fields that show an image retain their place.
- An exported PDF lists new form fields before new annotations. A form field created after an annotation appears below it in the exported PDF.
For more information, refer to the annotation customization guide and the forceRenderWidgetsInAnnotationsOrder API reference.
Changes refused by Document Engine
Document Engine can permanently refuse a change — for example, because of collaboration permissions. Before 1.26, an annotation or comment retained a refused change until the document reloaded. The annotation or comment now returns to the version that Document Engine holds, and the SDK restores it after a refused deletion.
When the SDK reverts a refused update, it emits annotations.update or comments.update, as it does for another user’s change. When it restores an annotation or comment after a refused deletion, it emits annotations.create or comments.create. If a listener for these events writes changes back, it shouldn’t reapply the refused change.
The SDK also emits the new sync.refused event once for each refused change, including changes saved automatically. Use the event to tell users that a change wasn’t saved:
instance.addEventListener("sync.refused", (refusal) => { console.warn("A change could not be saved:", refusal.error.message);});The listener receives an object with the following properties:
error— AnErrorwhose message can include the reason Document Engine gave. The message isn’t a stable code.affectedObject— The object or value that the refused change tried to save. The restored object can differ from it.modificationType— The refused operation, which is"CREATED","UPDATED", or"DELETED".
The event doesn’t report temporary network failures, conflicts, or retries, and the SDK never emits it in standalone mode. The instance.save() and instance.ensureChangesSaved() methods still report the refusal. The instance.hasUnsavedChanges() method reports pending work, not past refusals.
For more information, refer to the autosave guide and the sync.refused API reference.
Toolbar color buttons
Toolbar color buttons now include the selected color in their accessible name. For example, screen readers announce “Color Blue” or “Fill Color None.”
Tests that look for these buttons by their exact name, such as “Color” or “Font Color,” no longer find them. Match the start of the name instead:
// Before 1.26, the exact name matched.getByRole("button", { name: "Color", exact: true });
// The name now ends with the selected color, so match its start.getByRole("button", { name: /^Color/ });The color picker now closes when a user selects a custom color, as it does for preset colors.
For more information, refer to the accessibility guide.
React 19
The SDK now bundles React 19 instead of React 18. The SDK uses its own copy of React, so the public API is unchanged, and applications don’t require changes.
This release supports Document Engine 1.5.6 or later. Specific features in server-backed mode require newer versions:
- Document Engine 1.16.0 or later —
SearchType.WORD_BASED, PDF exports without password protection, and removing annotation notes after an XML Forms Data Format (XFDF) roundtrip. - Document Engine 1.18.0 or later — Document-defined annotation tab order,
Annotation.createdBy,overprintPreview, andblackRendering. - Document Engine 1.20.0 or later — Viewing and toggling PDF layers. This version also fixes text selection highlights that skip spaces between words in certain PDFs after optical character recognition (OCR).
- Document Engine 1.21.0 or later — Document order for annotations from an uploaded PDF when
forceRenderWidgetsInAnnotationsOrderistrue. This version isn’t released yet.
Document Engine ignores compound measurements, which work only in standalone mode.
For version requirements, refer to the Web SDK and Document Engine compatibility requirements guide.
For the previous release, refer to the Web SDK 1.25 release notes.