1.20 release notes

Nutrient Web SDK 1.20 deprecates the blocks UI customization API in favor of the ui slot configuration; adds support for default parameter values in PDF JavaScript; and tightens runtime validation across the model, toolbar, and tool item APIs. It also stops the secondary toolbar from permanently covering document content, speeds up Content Editor startup and thumbnails sidebar resizing, updates GdPicture, and ships a broad round of collaboration, forms, and rendering fixes. See the changelog for full details.

The blocks UI customization API is deprecated

The ui._blocks customization API is deprecated and will be removed in a future release. Use the ui slot configuration instead. If you customize the UI through blocks, migrate to the equivalent slot.

// Deprecated: block-based customization.
NutrientViewer.load({
  ui: {
    _blocks: {
      [NutrientViewer.Interfaces.Search]: ({ props }) => ({
        content: myCustomSearch(props),
      }),
    },
  },
});

// Use the equivalent slot instead.
NutrientViewer.load({
  ui: {
    search: (getInstance, id) => ({
      render: () => myCustomSearch(),
    }),
  },
});

Because _blocks isn’t part of the published type declarations, the console is the only channel available for this notice. Loading a configuration that uses it now logs one deprecation warning:

• Configuring the same component through both APIs logs an additional warning per component, naming the slot path and the block so you know exactly what to migrate. Which of the two renders depends on the component and on what the slot provides, so this case was previously invisible. The minimal UI preset hides every slot a block maps onto, so conflicts surface there too.
• Passing _blocks to instance.setUI() has never had an effect — the value is always overwritten with the current one — and now reports that instead of failing silently.

For the list of slots and what each one replaces, refer to the UI customization and supported slots guides.

Default parameter values in PDF JavaScript

PDF JavaScript function declarations now support default parameter values, so documents whose scripts rely on them evaluate correctly instead of failing to parse:

function formatTotal(amount, currency = "USD") {
  return amount + " " + currency;
}

For more information, refer to the JavaScript support guide.

Stricter validation for models, toolbars, and tool items

Model, toolbar, and tool item validation now runs on shared schemas rather than hand-written checks, which closes a set of holes where malformed input was accepted or surfaced as an opaque TypeError. Input that was previously tolerated now throws, so review any call site that passes values built from user input or an external source.

• Non-finite numbers (NaN, Infinity, -Infinity) are rejected where a number is expected — for example, Bookmark.sortKey and CustomOverlayItem.pageIndex.
• Malformed comments, mentionable users, and document descriptors report a named validation error. For example, new NutrientViewer.DocumentDescriptor(null) now throws DocumentDescriptor: Expected an object. instead of TypeError: Cannot destructure property 'filePath' of 'null'.
• instance.setMentionableUsers() stored its argument unchecked and now applies the same rules as the load() configuration path.
• avatarUrl and description on mentionable users are checked whenever they’re present, not only when they’re truthy, so values such as 0 and false are no longer accepted.
• Toolbar items, tool items, Document Editor footer items, and inline text selection toolbar items reject invalid string and mediaQueries values consistently across all variants.
• DOM nodes in tool items are validated by node type rather than with instanceof Node, so a node created in another realm — an iframe, for example — is accepted.

For any given invalid input, the field reported first is unchanged, so error strings you match on in existing code stay the same.

Read-only geometry model types

The geometry models — Rect, Point, Size, Inset, DrawingPoint, and TransformationMatrix — now expose read-only properties and the same standard Immutable Record method subset as every other model. This is a type-only change: Runtime behavior is untouched, and these objects were already immutable. TypeScript now reports an error where your code assigns to a property; use set() to derive a new value instead:

const rect = new NutrientViewer.Geometry.Rect({
  left: 0,
  top: 0,
  width: 100,
  height: 50,
});

// Previously allowed by the types, but never applied at runtime.
// rect.left = 10;

// Derive a new value instead.
const movedRect = rect.set("left", 10);

Secondary toolbar no longer covers document content

The secondary toolbar reserves scrollable space while it’s open instead of overlaying the document, so content underneath it is always reachable. The space is reserved above the first page with the default toolbar placement, and below the last page when toolbarPlacement is BOTTOM.

Performance improvements

• Content Editor startup is faster because fonts are cached and reused across editing sessions instead of being loaded again for each one.
• The thumbnails sidebar feels immediate while being resized: Thumbnails settle directly at their final position rather than animating into it, so the list no longer shifts after it renders and click targets stay steady.

Other additions

• GdPicture is updated to 14.4.7. Refer to the GdPicture changelog for details.
• Progressive page renders that exhaust WebAssembly memory now surface a typed out-of-memory error instead of retrying through direct rendering, which prevents memory-exhaustion crash loops on very large pages.

Collaboration and forms

• Fixes updates to annotations, comments, and form fields being silently discarded when Collaboration Permissions are enabled and the update was issued before Document Engine acknowledged the record’s creation.
• Fixes chained form field calculations not being fully recalculated when the document’s calculation order lists dependent fields before the fields they depend on.
• Fixes Document Compare requiring a trailing slash on the AI Assistant backendUrl.

Rendering and editing

• Fixes washed-out colors when rendering PDFs that use CMYK transparency groups with process black or DeviceN shadings.
• Fixes dashed lines with fractional dash patterns rendering as solid lines.
• Fixes free text callout annotations sometimes rendering text too small or clipped.
• Fixes ink strokes changing after they’re completed.
• Fixes a crash on Safari and iOS 15.4–16 when rendering text containing a URL.

User interface

• Fixes the viewer losing its scroll position when opening or closing the sidebar, which left it showing a blank page or jumping to the first page instead of staying on the current page.
• Fixes annotation placement when browser extensions load with custom toolbars.
• Fixes the loading skeleton showing its toolbar at the top when toolbarPlacement is set to BOTTOM.
• Fixes the text annotation opacity slider on mobile closing after a single step instead of following a press and drag to the chosen value.
• Fixes reopening the reply editor when returning to a comment thread with an unsaved edit.
• Fixes rich text annotation editor text selection spanning multiple nodes in the shadow DOM viewer variant.
• Fixes measurement settings modal colors for built-in and custom dark themes.

Loading, platform, and API reference

• Fixes aborting NutrientViewer.load() with an AbortSignal hanging instead of rejecting when the SDK is rendered in an iframe.
• Fixes a ReferenceError in the Node SDK when applying an importDocument document operation on Node.js 18 and 19, which have no global File.
• Fixes corrupted type signatures and missing property descriptions on several API reference pages, along with the annotation class names shown for defaultAnnotationsSidebarContent and defaultEditableAnnotationTypes.

For a full list of fixes, refer to the changelog.

For a complete list of changes, bug fixes, and improvements, refer to the changelog. For previous release notes, refer to the Web SDK 1.19 release notes. We appreciate your feedback and contributions as we continue to enhance Nutrient Web SDK.