Baseline UI migration guide

We’re excited to share that we’re migrating Web SDK components to Baseline UI, our in-house, accessibility-driven design system. This transition brings improvements in accessibility, customizability, performance, theming, and right-to-left (RTL) language support, along with a more consistent user experience. We’re rolling out these updates in phases, prioritizing a smooth and seamless experience for you.

As part of this migration, we’ve made some updates to the interface DOM structure, styling, and certain public class names. We’ve worked hard to keep these changes minimal and to ensure your existing implementations continue to work smoothly. While it’s not always possible to predict every unique customization, we expect most customizations to remain compatible. If you have any questions or run into any issues, reach out to us — our team is always happy to help!

That said, it’s not possible to provide an exact migration guide that covers all possible scenarios. The best way to approach upgrading is to keep an eye on the UI changes mentioned in the changelog and revalidate any customization or logic you may have written that relied on a particular selector or class name. We also maintain a list of these migrations for reference.

Theming and CSS variables

If you were depending on internal CSS variables for customizing the UI, you’ll need to update your code to use the new CSS variables. These CSS variables weren’t documented and weren’t intended to be used by customers, but we’re aware that some customers relied on them. The new CSS variables are documented in the [css-variables] section of the API reference.

Some of the licensed components still use the old CSS variables prefixed with --PSPDFKit-. All of these variables are gradually being replaced with unified CSS variables starting with --bui-.

Starting with Nutrient Web SDK 1.5, the recommended approach to theme the entire Web SDK is to use NutrientViewer.Configuration#theme, which now accepts a theme object. You should use the CSS variables only if you want to override the default theme for a section of the UI, rather than changing the theme for the whole Web SDK.

If you have any questions about theming or CSS variables, our documentation and support team are here to assist you.

The old public CSS classes haven’t changed and will remain unchanged. So, most customizations should continue to work. If your customizations rely on specific HTML nesting or DOM hierarchies, you may need to make minor adjustments. If you’re unsure or need help, let us know — we’re here to support you.

Migration timeline by version (most recent first)

Migrated in 1.5.0

  • Multi-select toolbar
  • Signatures sidebar
  • Print dialog
  • Form Creator popover
  • Loading screen

Migrated in 1.0.0

  • Link annotation toolbar
  • Image and signature annotation (image) toolbar
  • Stamp annotation toolbar
  • Text highlight and markup annotation toolbar
  • Content editor toolbar
  • Form creator toolbar
  • Ink eraser toolbar
  • Note annotation toolbar
  • Redaction toolbar
  • Shape annotation toolbars
  • Document crop toolbar

Migrated in 2024.8.0

  • Ink annotation toolbar
  • Text and Callout annotation toolbar
  • Annotations sidebar
  • Outline sidebar

Migrated in 2024.7

  • Bookmarks sidebar

Migrated in 2024.6.0

  • Primary (main) toolbar
  • Thumbnails sidebar
  • Password prompt dialog
  • Document Editor dialog
  • Search dialog

Migrated in 2024.4.0

  • Comments dialog
  • Comments popover

Migrated in 2024.3.0

  • Stamps dialog
  • Electronic signatures dialog

Not migrated yet

  • OCG layers sidebar
  • Measurements popover