Anvil to Anvil2

• for engineers, this is the migration guide for @servicetitan/design-system to @servicetitan/anvil2,
• for designers, this guide is for the switch from the Anvil Web to Anvil2 Figma library, and
• for product managers, this guide covers how to plan the swap and when a user-facing change needs a notice.

​

Migrating to Anvil2

​

React Requirement

​

Getting Started Documentation

​

Swapping Libraries

• In Figma, enable the Anvil2 library to start using the new components See the Figma docs to learn how to enable a library.
• In code, install the Anvil2 package:

npm install @servicetitan/anvil2

• Once the Anvil2 Web package is installed, components can be imported as follows.

import { Button } from "@servicetitan/anvil2";

​

CSS Updates

​

CSS Utilities

• Any utility classes from Anvil1 for flex, grid, display, position, alignment, height, width, z-indexing, border radius, line height, or white space have been removed.
• Spacing classes (margin and padding), now use inline and block properties rather than left/right/top/bottom. This enables easier internationalization using CSS but does require changing the class names. For example, .m-l-1 is now .m-inline-start-1. Learn more in the mdn docs.
• Spacing values (-1, -2, etc.) now use rem units for better accessibility.
• Most classes use CSS variables, which are provided by the ThemeProvider or AnvilProvider. A fallback value is provided for use outside of a provider.
• Utility classes can be imported all at once, or by utility type:

// all utils
import "@servicetitan/anvil2/assets/css-utils/a2-utils.css";
// by type
import "@servicetitan/anvil2/assets/css-utils/a2-border.css";
import "@servicetitan/anvil2/assets/css-utils/a2-color.css";
import "@servicetitan/anvil2/assets/css-utils/a2-font.css";
import "@servicetitan/anvil2/assets/css-utils/a2-spacing.css";

​

Component CSS

​

CSS Modules

​

Component Updates

​

Component Mapping

​

Date Picker values

function toDateString(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, "0");
  const day = String(date.getDate()).padStart(2, "0");
  return `${year}-${month}-${day}`;
}

// Anvil1
<DatePicker value={selectedDate} onChange={setSelectedDate} />

// Anvil2
<DateFieldSingle
  value={selectedDate ? toDateString(selectedDate) : null}
  onChange={(change) => {
    if (change.date) {
      const [year, month, day] = change.date.split("-").map(Number);
      setSelectedDate(new Date(year, month - 1, day));
    } else {
      setSelectedDate(null);
    }
  }}
/>

​

Layout in Anvil2

​

Component Layout Props

• Dialog
• Drawer
• Label
• Menu
• Popover
• Toast
• Tooltip

​

Other Notable Breaking Changes

​

Code

• Announcement
  • The actionName and onActionClick props have been removed. Instead, add action buttons as children of the Announcement.
• Badge/Tag → Chip
  • Separate component for Badge rather than variation of the Tag.
  • Use label instead of children.
• Banner → Alert
  • Replace action button props with action buttons in the children of the Alert.
• Pickers → Fields
  • Coming soon! All picker components (Date Picker, File Picker, etc.) will be replaced with field components.
• Modal → Dialog
  • The title and footer props have been replaced with the Dialog.Header and Dialog.Footer components, which can be passed as children of the Dialog.
  • Dialog should not be conditionally rendered - use the open prop to show or hide. Read more about this here.
• Drawer
  • Drawer should not be conditionally rendered - use the open prop to show or hide. Read more about this here.
• Option List → List View or Listbox
  • List Views include checkboxes.
  • Listboxes are generally used within confined spaces, such as a dropdown or side bar.
  • Both components use children rather than the options prop to render items.
• Progress Tracker → Stepper
  • The Stepper.Step sub-components should be children of a Stepper.List.
  • The Stepper.List, Stepper.Panel, Stepper.NextButton, Stepper.PrevButton, and Stepper.FinalPanel sub-components can be used as children of the Stepper.
• Select → Select Field for single selection or Multi Select Field for multiple selection
  • SelectFieldSync takes value as the option or null and onSelectedOptionChange. MultiSelectFieldSync takes value as an array and onSelectedOptionsChange. Options are { id, label }.
  • Both search options within an overlay. Pass options to SelectFieldSync or MultiSelectFieldSync, or loadOptions to SelectField or MultiSelectField for options loaded from a server.
  • Refer to the Select Field and Multi Select Field docs for implementation details.
• Table → Data Table (beta)
  • Data Table has been completely rewritten in Anvil2. Refer to the Data Table docs for more information.
• Tab
  • The Anvil2 Tab uses a few sub-components to construct the buttons and panels, and is an uncontrolled component.
  • In Anvil2, the controls and id props of the Tab.Panel and Tab.Button are used to determine which panel is opened by which button.
• Toast
  • The Anvil2 Toast implementation has undergone a complete overhaul. Rather than using state to control when a toast message is displayed, a set of toast methods are available to display, hide, and update toast messages can be used. See the Toast docs to learn how.
  • The Anvil team and the Front-End Platform team established a holistic solution to avoid issues with using both Anvil1 and Anvil2.

​

Design

• The Figma library now uses Figma variables to manage styles. This allows for easier text styling usage in addition to native dark mode support.
• Usage of instance swapping in several components, such as Dialog and Drawer, allowing for components to make better use of autolayouts.
• Improved support for suggested content in a component, such as options provided in the Combobox Popover and multiple Tabs in a single instance.
• More consistent application of visual states (e.g., Hover, Active, Focus).

​

Component Status in Figma

• Deprecated. An Anvil2 replacement exists. Do not use the Anvil1 component.
• Removed. The component is not used in Anvil1 or Anvil2.
• Considering. The Anvil team has not decided whether to move it to Anvil2.
• Coming soon. The component is on the roadmap and is not built yet.
• Same name, different behavior. The Anvil2 component keeps the Anvil1 name and behaves differently. Read that component’s page.

​

Components Omitted in Anvil2

• Backdrop
• Collapsible
• Mask
• More details
• Select
• Sidebar (integrated into Page)
• Snackbar

​

Components not currently available

• Color Picker **
• File Picker **
• Form *
• Inline Edit * Q1 FY27
• Status Light *

​

Migrate gradually as we release more components

​

For product managers

​

Plan the swap as BAU

​

Decide when users need a change notice