@servicetitan/anvil2

Anvil2 React Library

Anvil2 contains reusable components, fonts, icons, and more for building ServiceTitan products.

Hammer and Anvil2 Note

In this monorepo, there are both Hammer and Anvil2 packages. Hammer (e.g. @servicetitan/hammer-react), is the base library that the Anvil team maintains and @servicetitan/anvil2 builds on top of.

Anvil2 is more opinionated and ServiceTitan-specific, and can also include more complex components and customizations of Hammer.

Much of the source code for Anvil2 components actually exists in the packages/hammer-react package in this monorepo. When releasing updates, making changes in Hammer will automatically propagate to Anvil2, as long as the component/function/type is exported from the packages/anvil2 package as well.

Getting Started

Installation

We recommend installing Anvil2 by running the following npm command (or the equivalent yarn/pnpm command) in your project folder:

npm install @servicetitan/anvil2

Note on versions with MFEs

If you are using a Micro Front End (MFE) with the light bundle, the version of @servicetitan/anvil2 that is installed in the host app will be used when the MFE is loaded within the host app. If you need features or bug fixes from newer versions, update the version in the host app first.

Usage

Components

Components can be imported as named exports from the package root:

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

Icons

Anvil2 icons are expected to be used with the SVGR library, which will import SVGs as React components. SVGR should already be part of the latest @servicetitan/startup Webpack configuration.

Importing and using an icon:

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

import Warning from "@servicetitan/anvil2/assets/icons/material/round/warning.svg";
import Star from "@servicetitan/anvil2/assets/icons/material/round/star.svg";
import LocalSettings from "@servicetitan/anvil2/assets/icons/st/local_settings.svg";

export const Example = () => (
  <>
    <Icon svg={Warning} size="large" />
    <Button icon={Star} aria-label="Favorite" />
    <Button icon={LocalSettings}>Settings</Button>
  </>
);

CSS Utils

A set of CSS Utils classes are available. See the source code in our repo to see the full list.

import { Card } from "@servicetitan/anvil2";
import "@servicetitan/anvil2/assets/css-utils/utils.css";

export const Example = () => (
  <>
    <Card className="m-inline-4">Card with inline margin</Card>
  </>
);

NOTES

• If the utils.css file is already loaded by the host app, you might not need to import it.
• There is currently a known issue related to some temporary CSS overrides we've had to make to prevent some legacy CSS in the monolith from overriding Anvil2 component styles. If the CSS util you add doesn't work, and you see something like this in the browser inspector: :not(.aXNw) [data-anv='text'], you will need to instead add the styles you want in a custom className, and add an @layer around it:

@layer application {
  /* replaces .c-danger */
  .custom-class {
    color: var(--status-color-danger);
  }
}

We are actively working on a long-term solution with the Front-End Platform team.

AnvilProvider

When using the Anvil2 component library, we recommend wrapping the top level of your app in the AnvilProvider component, which also supports light/dark themes, localization, and data-tracking-id configurations:

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

<AnvilProvider themeData={...} localizationData={...} trackingIdData={...}>
  ...
</AnvilProvider>

Data Tracking IDs for FullStory

In order to enable consistent FullStory data tracking with Anvil2 components, a data-tracking-id is automatically generated for all interactive components. This id will only change if certain props change, which are determined on a per-component basis.

If your team or product already has a different strategy for tagging components in place, you can disable the auto-generated data-tracking-id tags using the AnvilProvider.trackingIdData or TrackingProvider.optOut:

// Using AnvilProvider
<AnvilProvider trackingIdData={{ optOut: true }}>...</AnvilProvider>

// Using TrackingProvider
<TrackingProvider scope="ST" optOut>...</TrackingProvider>

Documentation

You can read the Anvil2 docs at: https://anvil.servicetitan.com/

Contributing

We welcome contributions of all kinds from design to code!

Please reach out to our team in #ask-designsystem if you would like to make a contribution.

Check out the root-level Contributing docs for more details on making changes to this package.