Pivot Docs

    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.




    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:

    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 {}