Migration Guide

This guide covers migrating from the internal @nve/* packages to the new open source @nvidia-elements/* packages.

Agent Skill

Agents can leverage the migration skill by calling the skill from the Elements CLI or MCP.

Overview

The Elements Design System is now hosted and developed in a public GitHub repository. Packages are now published to the public npm registry under the @nvidia-elements scope. The component APIs, tag names, and theming system remain the same. The primary changes are package names, import paths, and registry configuration.

Stability and Versioning

Teams have run Elements in production since 2022, and NVIDIA already released it internally as 1.x. The move to open source changes the package scope to @nvidia-elements/*, but it does not reset the maturity of the system.

NVIDIA published the initial public open source packages as 0.x while the project completed its public release migration. Treat these 0.x versions as transitional open source preview releases, not proof that Elements itself is experimental or newly developed.

Elements moved from public 0.x prerelease versions to 2.0.0 for the stable open source release. This means there is no public 1.0.0 release under the @nvidia-elements/* scope. The missing public 1.0.0 is intentional: 1.x represents the prior internal production generation, and 2.0.0 represents the next stable generation under the public @nvidia-elements/* scope.

Migration Steps

1. Update Registry Configuration

The @nvidia-elements packages are on the public npm registry and require no special registry configuration. Internal teams should continue to use Artifactory regardless of which package scope. Artifactory proxies the public npm registry automatically.

2. Update Dependencies

In your package.json, replace the old scope names with the new ones:

3. Update Source Imports

Replace import paths throughout your source code:

Deprecations & Removals

The following are the active deprecations. Each next major release removes the prior deprecations. Read more about the versioning and deprecation cycle policy.

Logo removed

The nve-logo component no longer includes the NVIDIA SVG logo; consumers must provide their own SVG as child content in the default slot.

Popover Behavior Triggers deprecated

Before native HTML popovers, popovers required behaviorTrigger or behavior-trigger for stateful popovers. The native HTML popover API replaces this approach.

Combobox No Tags removed

Elements removed the notags attribute. Use tag-layout="hidden" instead so all tag layout modes use the same attribute.

Layout Full removed

The grow property now uses full instead to avoid confusion with flexbox grow behavior.

Typography "eyebrow" removed

The typography eyebrow utility no longer exists, to align with the standardized semantic names and size options available.

@nve/testing removed

The custom test utilities are no longer supported in the public scope.

Scoped Tags removed

Avoid @nve/elements/scoped. Instead, consuming applications define their own tag name and leverage the @lit-labs/scoped-registry-mixin package directly.

Maglev - CSS Entrypoints removed

Maglev - CSS Prefix removed

Update any CSS Custom property usage

Maglev - Attribute Prefix removed

Update style utility attributes

Maglev - HTML Prefix removed

Update HTML elements

Maglev - App Header removed

nve-page-header replaces the early Maglev scoped package mlv-app-header.

Maglev - Alert Banner removed

The alert banner component no longer exists. Use nve-alert-group with the prominence="emphasis" option.

Maglev - JSON Viewer removed

The JSON viewer element is an internal API. You can access this API via the public exports but should avoid using it. Use nve-codeblock or nve-monaco-input for JSON content rendering.

Maglev - Icon Names removed

The following icons now use new names:

Maglev - Icon Button Name Directions removed

With the deprecation of directional icons the icon button now requires a explicit direction.