V12 migration guide

The following guide will help you migrate to V12 and explain the major changes.

Component imports

As part of the Next.js compatibility work, we have removed the dot notation syntax from our components. Instead all our components are now named exports. See the list below of all affected components and their new import names.

Breadcrumbs

import {
  Breadcrumbs,
  BreadcrumbsItem,
  BreadcrumbsLink,
} from "@arc-ui/components/Breadcrumbs";

Columns

import { Columns, ColumnsCol } from "@arc-ui/components/Columns";

ContentSwitcher

import {
  ContentSwitcher,
  ContentSwitcherContent,
  ContentSwitcherList,
  ContentSwitcherTab,
} from "@arc-ui/components/ContentSwitcher";

ContentSwitcherDropdown

import {
  ContentSwitcherDropdown,
  ContentSwitcherDropdownContent,
} from "@arc-ui/components/ContentSwitcherDropdown";

Filter

import { Filter, FilterItem } from "@arc-ui/components/Filter";

This components structure has also changed. See below for an example.

<Filter
  controls={[
    {
      label: "Tag1",
    },
    {
      label: "Tag2",
    },
  ]}
>
  <FilterItem tags={["Tag1", "Tag2"]}>
    Item 1
  </FilterItem>
  <FilterItem tags={["Tag1"]}>
    Item 2
  </FilterItem>
</Filter>,

Grid

import {
  Grid,
  GridRow,
  GridCol,
  type GridValue,
  type AlignmentValue,
} from "@arc-ui/components/Grid";

Group

import { Group, GroupItem } from "@arc-ui/components/Group";

Image

import { Image, ImageSource } from "@arc-ui/components/Image";

Poster

import { Poster, PosterImage, PosterVideo } from "@arc-ui/components/Poster";

ProgressStepper

import {
  ProgressStepper,
  ProgressStepperItem,
} from "@arc-ui/components/ProgressStepper";

RadioCardGroup

import {
  RadioCardGroup,
  RadioCardGroupInput,
} from "@arc-ui/components/RadioCardGroup";

RadioGroup

<RadioGroup.RadioButton /> has now become <RadioGroupInput />

import { RadioGroup, RadioGroupInput } from "@arc-ui/components/RadioGroup";

SiteFooter

import {
  SiteFooter,
  SiteFooterItem,
  SiteFooterItemGroup,
} from "@arc-ui/components/SiteFooter";

SiteHeaderV2

import {
  SiteHeaderV2,
  SiteHeaderV2Column,
  SiteHeaderV2Item,
  SiteHeaderV2ItemGroup,
  SiteHeaderV2NavItem,
  SiteHeaderV2NavItemWithSubNav,
  SiteHeaderV2NodeItem,
  SiteHeaderV2SubNavItem,
  SiteHeaderV2VerticalDivider,
} from "@arc-ui/components/SiteHeaderV2";

SkipLink

import { SkipLink, SkipLinkItem } from "@arc-ui/components/SkipLink";

Tabs

import { Tabs, TabsList, TabsItem } from "@arc-ui/components/Tabs";

Toast

import { Toast, ToastNotification } from "@arc-ui/components/Toast";

UniversalHeader

import { UniversalHeader, UniversalHeaderItem } from "@arc-ui/components/src";

Themes

Arc V12 supports multiple themes. If you have an app that is currently using arc components, all you need to do is import the BT Enterprise theme and the component styles. The rest of the guide will show which packages have changed, and how to migrate.

import "@arc-ui/themes/lib/bt-enterprise.css";
import "@arc-ui/components/lib/styles.css";

Icons

The icons package imports have changed to be shorter, and now contain both ee and bt icons. They have also been changed to data uri's. This is because of various requirements that were not possible with the react versions. As these are intended to be used in conjunction with our Icon component, we don't offer the React icons anymore. Current formats are the js constants as data uri strings, css and scss.

@arc-ui/icons/BtIconInfo @arc-ui/icons/EeIconChevronDown

If you were using icons directly, you can import our Icon component and pass the icon in and it should work as it did before. The icon component is styled to take the width and height of its parent if no size prop is provided.

Tokens

Tokens have a separate package for each theme. All the token names have changed, so these will need to be manually updated in your codebase if you're using them directly.

@arc-ui/tokens has been replaced by:

@arc-ui/tokens-bt-enterprise @arc-ui/tokens-bt-business @arc-ui/tokens-ee

JSON Tokens

@arc-ui/tokens-json has been removed. JSON tokens are now available at @arc-ui/tokens-<brand>/dist/json

Fonts

@arc-ui/fonts has been removed as the fonts are now provided by the theme package:

SCSS Tokens

@arc-ui/tokens-scss has been removed. JSON tokens are now available at @arc-ui/tokens-<brand>/dist/scss

Rehydration

In earlier versions of Arc you could use the component library in a non react project. This is something that we have slowly stopped supporting and have completely removed in V12. As a result @arc-ui/bundle has been removed.

Next.js app router

Arc components will work in the Next.js app router without you having to provide "use client" directives. Please note that anything imported from the main bundle WILL ALWAYS RENDER ON THE CLIENT as there is a "use client" directive at the top of the file. In order to get the most out of the app router, import components individually as opposed to the main bundle. This is a work in progress, so please contact a member of the Arc team should you have any issues that you need help with.

Removed Features

Alert: removed dark pathway styling.
Badge: removed dark pathway styling, removed large size.
HeadingProposition: removed the HeadingProposition subcomponent from Heading.
Pagination: removed dark pathway styling
PaginationSimple: removed dark pathway styling
ProgressBar: removed dark pathway styling
ProgressStepperItem: removed dark pathway styling
Tag: removed dark pathway styling

Updated property names

Alert

Alert properties link and linkText have been replaced by a links property to enable multiple links to be included in the component.

Elevation

Elevation property elevationLevel changed to level. This property now ranges from 1-5 previously this was 1-2.

Inputs

Switch property labelSize has been renamed to size. Select property selectSize has been renamed to size. TextInput and Datepicker property inputSize has been renamed to size. labelSizeproperty has been removed from TextInput, Select, RadioGroup, RadioGroupInput and DatePicker. The size of the label is now linked to the size of the input.

Surface & Box

The Surface background names have changed to be more generic, to enable better theming support.

Old	New
black	dark-black
brand-flat	dark-brand-01
brand	dark-brand-02
dark	dark-neutral-01
darker	dark-neutral-02
coral	light-brand-01
turquoise	light-brand-02
lighter	light-neutral-01
light	light-neutral-02
white	light-white

Media Card

Renamed img property to media and added support for YouTube and Vimeo videos.

Removed Components

Base

This has been replaced by the <Theme /> component. If your just using one theme in your project, wrap your entire app in the <Theme /> Component, and remove all instances of Base.

Card

This has been removed and has been replaced by four new card components. <MediaCard /> <InformationCard /> <TypographyCard /> <ImpactCard />

Clock

This component has been removed.

Curve

This feature has been removed from the design language and should not be included in future designs.

SiteHeader

This has been replaced with SiteHeaderV2

Deprecated Components

Poster

This will be removed and replaced by heroBanner in a future release.

Button

This will be removed in a future major release. Please upgrade to buttonV2 or heroButton

Component imports​

Breadcrumbs​

Columns​

ContentSwitcher​

ContentSwitcherDropdown​

Filter​

Grid​

Group​

Image​

Poster​

ProgressStepper​

RadioCardGroup​

RadioGroup​

SiteFooter​

SiteHeaderV2​

SkipLink​

Tabs​

Toast​

UniversalHeader​

Themes​

Icons​

Tokens​

JSON Tokens​

Fonts​

SCSS Tokens​

Rehydration​

Next.js app router​

Removed Features​

Updated property names​

Alert​

Elevation​

Inputs​

Surface & Box​

Media Card​

Removed Components​

Base​

Card​

Clock​

Curve​

SiteHeader​

Deprecated Components​

Poster​

Button​

Component imports

Breadcrumbs

Columns

ContentSwitcher

ContentSwitcherDropdown

Filter

Grid

Group

Image

Poster

ProgressStepper

RadioCardGroup

RadioGroup

SiteFooter

SiteHeaderV2

SkipLink

Tabs

Toast

UniversalHeader

Themes

Icons

Tokens

JSON Tokens

Fonts

SCSS Tokens

Rehydration

Next.js app router

Removed Features

Updated property names

Alert

Elevation

Inputs

Surface & Box

Media Card

Removed Components

Base

Card

Clock

Curve

SiteHeader

Deprecated Components

Poster

Button