Getting started
Step 1 - Configure the npm registry
Create an .npmrc file in your project's root directory with
the following content, replacing the placeholder values with your
Base64-encoded Personal Access Token:
@fcsamerica:registry=https://pkgs.dev.azure.com/fcsamerica/_packaging/AppDev/npm/registry/
//pkgs.dev.azure.com/fcsamerica/_packaging/AppDev/npm/registry/:username=fcsamerica
//pkgs.dev.azure.com/fcsamerica/_packaging/AppDev/npm/registry/:_password=[REPLACE WITH BASE64 PAT]
//pkgs.dev.azure.com/fcsamerica/_packaging/AppDev/npm/registry/:email=[your email address]
//pkgs.dev.azure.com/fcsamerica/_packaging/AppDev/npm/:username=fcsamerica
//pkgs.dev.azure.com/fcsamerica/_packaging/AppDev/npm/:_password=[REPLACE WITH BASE64 PAT]
//pkgs.dev.azure.com/fcsamerica/_packaging/AppDev/npm/:email=[your email address]A Personal Access Token with read, write, and manage permissions for Packages can be generated at https://dev.azure.com/fcsamerica/_usersSettings/tokens.
Important: The .npmrc file contains
sensitive credentials and must not be committed to source control.
Step 2 - Install the package
npm install @fcsamerica/pivot
This installs the latest release and saves a caret range (for example
"^2.1.0") to your
package.json, so future installs pick up new minor and patch
releases but never a new major version.
Step 3 - Register the stylesheets
Add the following entries to the styles array in your
angular.json file:
For FCS branding:
"styles": [
"node_modules/@fcsamerica/pivot/dist/style/brands/fcs-tokens.css",
"node_modules/@fcsamerica/pivot/dist/style/pivot.css"
]For AgDirect branding:
"styles": [
"node_modules/@fcsamerica/pivot/dist/style/brands/agd-tokens.css",
"node_modules/@fcsamerica/pivot/dist/style/pivot.css"
]Step 4 - Import the component library
Add import '@fcsamerica/pivot'; to your application's
main.ts entry point.
Step 5 - Install the brand fonts
Add the fonts used by the design system to your project:
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap" rel="stylesheet"
/>
<link rel="stylesheet" href="https://use.typekit.net/isl2nla.css" />Proxima Nova and Mokoko are licensed Adobe Fonts. Contact the XD Team to get help configuring the Typekit kit ID for your project, or create your own Adobe Fonts kit if your team has an Adobe subscription.
If you're adding Font Awesome icons to Pivot components, install the Font Awesome kit and see Using Font Awesome icons.
Step 1
Add the design token CSS and base theme CSS to your project. These define the CSS custom properties that all Pivot components depend on for colors, spacing, and typography:
For FCS branding:
<!-- Pivot UX Design Tokens & Base Styles -->
<link rel="stylesheet" href="https://ux-components.fcsamerica.com/cdn/2.1.0/style/brands/fcs-tokens.css" />
<link rel="stylesheet" href="https://ux-components.fcsamerica.com/cdn/2.1.0/style/pivot.css" />For AgDirect branding:
<!-- Pivot UX Design Tokens & Base Styles -->
<link rel="stylesheet" href="https://ux-components.fcsamerica.com/cdn/2.1.0/style/brands/agd-tokens.css" />
<link rel="stylesheet" href="https://ux-components.fcsamerica.com/cdn/2.1.0/style/pivot.css" />Step 2
Add the fonts used by the design system to your project:
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap" rel="stylesheet"
/>
<link rel="stylesheet" href="https://use.typekit.net/isl2nla.css" />Proxima Nova and Mokoko are licensed Adobe Fonts. Contact the XD Team to get help configuring the Typekit kit ID for your project, or create your own Adobe Fonts kit if your team has an Adobe subscription.
If you're adding Font Awesome icons to Pivot components, install the Font Awesome kit and see Using Font Awesome icons.
Step 3
Add the library script to load all of the web components:
<script type="module" src="https://ux-components.fcsamerica.com/cdn/2.1.0/index.js"></script>Or load only the components a page uses. Each component has its own entry point, and shared code is downloaded once no matter how many you load:
<script type="module" src="https://ux-components.fcsamerica.com/cdn/2.1.0/components/button.js"></script>
Load one version of Pivot per page. Two versions can't register the same
pivot-* elements, so the second one fails to load.
Choosing a version
-
Exact version (
/cdn/2.1.0/): recommended for production. The files at this address never change. -
Major version (
/cdn/2/): picks up new minor and patch releases automatically, without breaking changes. Files at this address are cached for a few minutes, so updates arrive shortly after each release. -
/cdn/latest/: always the newest release, including new major versions with breaking changes. Use it for prototypes only, never in production.
Step 4
Add CUSTOM_ELEMENTS_SCHEMA to every Angular component that
uses a Pivot element:
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
@Component({
selector: 'app-example',
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `<pivot-button>Click me</pivot-button>`,
})
export class Example {}
Why CSS files? Pivot components use Shadow DOM, so their internal styles
are encapsulated. However, they reference CSS custom properties (e.g.
var(--fcs-brand-dark-green-700)) that must be defined on
:root on the host page. Without
fcs-tokens.css and pivot.css, components render
but fall back to unstyled browser defaults.
Using Font Awesome icons
Pivot doesn't load or depend on Font Awesome. The icons components draw
themselves, such as the accordion chevron and field error icons, are built in.
You only need Font Awesome for icons you add to a component, such as a leading
icon in pivot-input or the icon in
pivot-icon-button. Install the kit on your page and place an
<i> element in the component's icon slot:
<pivot-input pivot-label="Username">
<i slot="icon-leading" class="fa-solid fa-user"></i>
</pivot-input>
<pivot-icon-button pivot-label="Settings">
<i class="fa-solid fa-gear"></i>
</pivot-icon-button>
Pivot's icon slots are styled for <i> and
<svg> elements.
Choosing a kit technology
Font Awesome kits draw icons with either web fonts or SVG + JS, set in your kit's settings. Both work with Pivot on a regular page:
-
Web fonts: the
<i>element stays in the page and is drawn with the icon font. -
SVG + JS: the kit replaces each
<i>with an<svg>and copies itsslotattribute, so the icon stays in the same slot.
Angular
With Angular's default view encapsulation (Emulated) or
None, icons in your templates work the same as on any other page.
If an icon changes at runtime, for example through a
[class] binding, use a web font kit. An SVG + JS kit replaces the
<i> element Angular rendered, so later binding updates go
to an element that's no longer on the page. With an SVG + JS kit, change icons
by rendering a new element instead, for example with @if or
@switch.
Use the kit rather than the <fa-icon> component from
angular-fontawesome: Pivot's icon slots only style
<i> and <svg> elements.
Inside your own shadow root
Font Awesome only finds and styles icons in the main page. If you place Pivot
components inside your own shadow root, such as an Angular component using
ViewEncapsulation.ShadowDom or another web component, every Font
Awesome icon in that shadow root needs extra setup, whether or not it's inside
a Pivot component. Once that setup is done, icons in Pivot components work the
same as any other icon there. Inline <svg> icons need no
setup.
SVG + JS
Point Font Awesome at the shadow root and add its stylesheet there. Without the stylesheet, icons render without Font Awesome's sizing.
import {
AfterViewInit,
Component,
CUSTOM_ELEMENTS_SCHEMA,
ElementRef,
ViewEncapsulation,
} from '@angular/core';
declare global {
interface Window {
FontAwesome?: {
dom: {
css(): string;
watch(options: {
autoReplaceSvgRoot?: Node;
observeMutationsRoot?: Node;
}): void;
};
};
}
}
@Component({
selector: 'app-profile',
encapsulation: ViewEncapsulation.ShadowDom,
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `
<pivot-input pivot-name="username" pivot-label="Username">
<i slot="icon-leading" class="fa-solid fa-user"></i>
</pivot-input>
`,
})
export class ProfileComponent implements AfterViewInit {
constructor(private host: ElementRef<HTMLElement>) {}
ngAfterViewInit(): void {
const root = this.host.nativeElement.shadowRoot;
const fontAwesome = window.FontAwesome;
if (!root || !fontAwesome) return;
// Font Awesome's CSS, added to this shadow root
const style = document.createElement('style');
style.textContent = fontAwesome.dom.css();
root.prepend(style);
// Convert icons in this shadow root, including ones added later
fontAwesome.dom.watch({
autoReplaceSvgRoot: root,
observeMutationsRoot: root,
});
}
}
Font Awesome must be loaded before this runs. Load it with a regular
<script> tag in index.html or through the
scripts array in angular.json.
Web fonts
Include Font Awesome's CSS in two places: on the main page, which loads the icon font, and in the component's styles, which applies the icon classes inside the shadow root. Browsers don't load fonts declared only inside a shadow root, and the main page's icon classes don't reach into it, so either one alone leaves icons blank. A kit only adds its CSS to the main page, so for the component's styles use Font Awesome's CSS files from its npm package.
Angular: binding dynamic values to component attributes
There are two ways to bind dynamic values to Pivot component attributes in Angular templates.
Option 1 — [attr.] prefix (recommended)
Use the attr. prefix to set the HTML attribute directly:
<pivot-input [attr.pivot-label]="myValue"></pivot-input>Option 2 — camelCase property binding
Bind to the camelCase equivalent of the attribute name:
<pivot-input [pivotLabel]="myValue"></pivot-input>
This requires CUSTOM_ELEMENTS_SCHEMA in the Angular component to
suppress unknown-property errors:
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
@Component({
selector: 'app-example',
schemas: [CUSTOM_ELEMENTS_SCHEMA],
template: `<pivot-input [pivotLabel]="myValue"></pivot-input>`,
})
export class ExampleComponent {}