MIGRATION-GUIDE.md

Nova React migration guide

V3

V2 has been our most stable library release ever. It's been around for nearly 2 years. V3 will set up an even more stable future. It is our most standalone and future facing library ever.

Most of the examples have been migrated for a while with these latest breaking changes to ease the transistion. So if you've copied examples over recently those should be good to go for the most part.

NOTE: Before starting the migration you will want to download the latest of V2. This version has marked elements for deprecation with some helpful warnings to ease the upgrade.

React 19 required

We had support for React 19 since day one of it's release. However, primarily due to how React 19 simplifies ref forwarding, React 19 is now required. This dramatically simplifies our library, and makes our components up to 2x faster.

React 19 upgrade guide ➹.

Decoupling icons

In this version we severed the icons package from the library, making it completely optional. This allows you to bring your own icons, or in some senarios, no icons at all. This aligns React with our other libraries' icons packaging stragey.

AccordionToggleIcon required properties

AccordionToggleIcon now requires elementClosed, elementOpen properties.

Before:

<AccordionToggleIcon />

After:

import { VisaChevronDownTiny, VisaChevronRightTiny } from '@visa/nova-icons-react';

...

<AccordionToggleIcon
	elementClosed={<VisaChevronRightTiny rtl />}
	elementOpen={<VisaChevronDownTiny />}
/>

The tag property is also no longer supported.

MessageIcon migration

We migrated BannerIcon, DialogIcon, FlagIcon, MessageIcon, SectionMessageIcon from the React library to the consolidated MessageIcon component in the React icons library.

Before:

import { BannerIcon, DialogIcon, FlagIcon, MessageIcon, SectionMessageIcon } from '@visa/nova-react';

After:

import { MessageIcon } from '@visa/nova-icons-react';

The messageType property is no longer passed automatically to the MessageIcon. So be sure to pass it to the icon.

• BannerIcon

  Before:

  <Banner messageType="warning">
    <BannerIcon />
  </Banner>

  After:

  <Banner messageType="warning">
    <MessageIcon messageType="warning" />
  </Banner>

• DialogIcon

  Before:

  <Dialog messageType="warning">
    <DialogIcon />
  </Dialog>

  After:

  <Dialog messageType="warning">
    <MessageIcon messageType="warning" />
  </Dialog>

• FlagIcon

  Before:

  <Flag messageType="warning">
    <FlagIcon />
  </Flag>

  After:

  <Flag messageType="warning">
    <MessageIcon messageType="warning" />
  </Flag>

• SectionMessageIcon

  Before:

  <SectionMessage messageType="warning">
    <SectionMessageIcon />
  </SectionMessage>

  After:

  <SectionMessage messageType="warning">
    <MessageIcon messageType="warning" />
  </SectionMessage>

Close icons

Child(ren) are now required for BannerCloseButton, DialogCloseButton, FlagCloseButton, MessageCloseButton, SectionMessageCloseButton. The <VisaCloseTiny /> component from the icons library is no longer the default child.

• BannerCloseButton

  Before:

  <BannerCloseButton />

  After:

  <BannerCloseButton>
    <VisaCloseTiny />
  </BannerCloseButton>

• DialogCloseButton

  Before:

  <DialogCloseButton />

  After:

  <DialogCloseButton>
    <VisaCloseTiny />
  </DialogCloseButton>

• FlagCloseButton

  Before:

  <FlagCloseButton />

  After:

  <FlagCloseButton>
    <VisaCloseTiny />
  </FlagCloseButton>

• SectionMessageCloseButton

  Before:

  <SectionMessageCloseButton />

  After:

  <SectionMessageCloseButton>
    <VisaCloseTiny />
  </SectionMessageCloseButton>

The ariaLabel property has been changed to aria-label to keep it consistent with the dom property's spelling.

MessageContext and useMessage removed

These were used to pass the messageType to the MessageIcon component. Obviously, since the MessageIcon has been migrated these are no longer being used, thus were removed.

Progress component removed

Migrate to ProgressCircular, ProgressLinear

BadgeNumber component removed

Migrate to Badge with badgeVariant="number" property

Migrated Typography varients

Migrate varients 'color-default' | 'color-subtle' to colorScheme

Component type casting migrated to string literal

Before:

<Button<AchorElement> />

After:

<Button<'a'> />

Here is a helpful regex to find all element type castings in your codebase: ^\s*<[^>|^ ]*<

Breadcrumbs

The ariaLabel property has been changed to aria-label to keep it consistent with the dom property's spelling.