Migration Guide
This guide covers migrating from the internal @nve/* packages to the new open source @nvidia-elements/* packages.
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.
| Internal Package | New Package |
|---|---|
@nve/elements |
@nvidia-elements/core |
@nve/styles |
@nvidia-elements/styles |
@nve/themes |
@nvidia-elements/themes |
@nve/monaco |
@nvidia-elements/monaco |
@nve-labs/forms |
@nvidia-elements/forms |
@nve-labs/cli |
@nvidia-elements/cli |
@nve-labs/code |
@nvidia-elements/code |
@nve-labs/create |
@nvidia-elements/create |
@nve-labs/markdown |
@nvidia-elements/markdown |
@nve-labs/media |
@nvidia-elements/media |
@nve-labs/lint |
@nvidia-elements/lint |
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:
"dependencies": {
- "@nve/elements": "^1.67.0",
- "@nve/themes": "^1.12.0",
- "@nve/styles": "^1.14.0"
+ "@nvidia-elements/core": "^0.0.3",
+ "@nvidia-elements/themes": "^0.0.4",
+ "@nvidia-elements/styles": "^0.0.3"
}
The 0.x versions of the new packages contain the same non-deprecated components as the latest internal releases. Version numbers reset as part of the migration to public npm. A stable 1.0 release follows later.
3. Update Source Imports
Replace import paths throughout your source code:
- import '@nve/elements/button/define.js';
- import { Button } from '@nve/elements/button';
+ import '@nvidia-elements/core/button/define.js';
+ import { Button } from '@nvidia-elements/core/button';
- import '@nve/themes/dist/index.css';
+ import '@nvidia-elements/themes/dist/index.css';
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.
<nve-logo aria-label="NVIDIA"></nve-logo>
<nve-logo>
<img src="./logo.svg" alt="NVIDIA" />
</nve-logo>
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.
<nve-tooltip trigger="tooltip-btn" behavior-trigger position="top" hidden>hello there</nve-tooltip>
<nve-button id="tooltip-btn">tooltip</nve-button>
<nve-tooltip id="my-tooltip" position="top">hello there</nve-tooltip>
<nve-button popovertarget="my-tooltip">tooltip</nve-button>
Layout Full deprecated
The grow property now uses full instead to avoid confusion with flexbox grow behavior.
<div nve-layout="grow"></div>
<div nve-layout="full"></div>
Typography "eyebrow" deprecated
The typography eyebrow utility no longer exists, to align with the standardized semantic names and size options available.
<div nve-text="eyebrow"></div>
<div nve-text="label sm"></div>
@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
/* before */
@import '@maglev/elements/index.css';
@import '@maglev/elements/inter.css';
@import '@nvidia-elements/themes/fonts/inter.css';
@import '@nvidia-elements/themes/index.css';
@import '@nvidia-elements/themes/high-contrast.css';
@import '@nvidia-elements/themes/reduced-motion.css';
@import '@nvidia-elements/themes/compact.css';
@import '@nvidia-elements/themes/dark.css';
@import '@nvidia-elements/themes/debug.css';
@import '@nvidia-elements/styles/typography.css';
@import '@nvidia-elements/styles/layout.css';
@import '@nvidia-elements/styles/view-transitions.css';
Maglev - CSS Prefix removed
Update any CSS Custom property usage
.selector {
color: var(--mlv-ref-color-brand-green-200);
}
.selector {
color: var(--nve-ref-color-brand-green-200);
}
Maglev - Attribute Prefix removed
Update style utility attributes
<html mlv-theme="...">
<div mlv-layout="...">
<p mlv-text="...">
<html nve-theme="...">
<div nve-layout="...">
<p nve-text="...">
Maglev - HTML Prefix removed
Update HTML elements
<mlv-button>...</mlv-button>
<nve-button>...</nve-button>
Maglev - App Header removed
nve-page-header replaces the early Maglev scoped package mlv-app-header.
<mlv-app-header>
...
</mlv-app-header>
<nve-page-header>
<nve-logo slot="prefix" size="sm">NV</nve-logo>
<h2 slot="prefix" nve-text="heading sm">Infrastructure</h2>
<nve-button selected container="flat"><a href="#">Link 1</a></nve-button>
<nve-button container="flat"><a href="#">Link 2</a></nve-button>
<nve-icon-button slot="suffix" interaction="emphasis" size="sm">EL</nve-icon-button>
</nve-page-header>
Maglev - Alert Banner removed
The alert banner component no longer exists. Use nve-alert-group with the prominence="emphasis" option.
<nve-alert-banner>
<nve-alert closable>
<span slot="prefix">Standard</span> banner message
</nve-alert>
</nve-alert-banner>
<nve-alert-group prominence="emphasis" container="full">
<nve-alert closable>
<span slot="prefix">Standard</span> banner message
</nve-alert>
</nve-alert-group>
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:
| before | after |
|---|---|
| chevron-right | chevron |
| chevron-down | chevron |
| chevron-left | chevron |
| additional-actions | more-actions |
| analytics | pie-chart |
| annotation | transparent-box |
| app-switcher | switch-apps |
| assist | chat-bubble |
| checkmark | check |
| date | calendar |
| docs | book |
| expand-full-screen | maximize |
| expand-panel | arrow-stop |
| collapse-panel | arrow-stop |
| failed | x-circle |
| favorite-filled | star |
| favorite-outline | star-stroke |
| information | information-circle-stroke |
| maintenance | wrench |
| navigate-to | arrow |
| open-external-link | arrow-angle |
| location | map-pin |
| pinned-1 | pin |
| project | folder |
| settings | gear |
| user | person |
| video-pause | pause |
| video-play | play |
| video-stop | stop |
| visible | eye |
| warning | exclamation-triangle |
Maglev - Icon Button Name Directions removed
With the deprecation of directional icons the icon button now requires a explicit direction.
<nve-icon name="chevron-left"></nve-icon>
<nve-icon name="beginning"></nve-icon>
<nve-icon name="beginning-left"></nve-icon>
<nve-icon name="collapse-panel"></nve-icon>
<nve-icon name="navigate-back"></nve-icon>
<nve-icon name="chevron-right"></nve-icon>
<nve-icon name="end"></nve-icon>
<nve-icon name="expand-panel"></nve-icon>
<nve-icon name="navigate-to"></nve-icon>
<nve-icon name="carousel-horizontal"></nve-icon>
<nve-icon name="chevron-down"></nve-icon>
<nve-icon name="thumbs-down"></nve-icon>
<nve-icon name="chevron" direction="left"></nve-icon>
<nve-icon name="beginning" direction="left"></nve-icon>
<nve-icon name="arrow-stop" direction="left"></nve-icon>
<nve-icon name="navigate-back" direction="left"></nve-icon>
<nve-icon name="chevron" direction="right"></nve-icon>
<nve-icon name="end" direction="right"></nve-icon>
<nve-icon name="arrow-stop" direction="right"></nve-icon>
<nve-icon name="arrow" direction="right"></nve-icon>
<nve-icon name="carousel-horizontal" direction="right"></nve-icon>
<nve-icon name="chevron" direction="down"></nve-icon>
<nve-icon name="thumb" direction="down"></nve-icon>