Angular

Angular has great support for custom elements and can be used directly.

With that being said, while Angular can be used with Forge, there are some caveats to be aware of:

• The Angular compiler is not designed to work with custom elements, so you will need to use the CUSTOM_ELEMENTS_SCHEMA to disable the compiler from throwing errors when it comes across any elements it does not recognize.
• Using ngModel, formControl or formControlName does not work out of the box. You would need to implement ControlValueAccessor directives for custom elements to integrate with Angular forms.
• Angular’s change detection does not run in response to changes outside of the Angular context, so you might need to use NgZone to manually trigger change detection where necessary.

Forge + Angular Adapter

To make using Forge with Angular more seamless, we have created an adapter library that helps with the issues mentioned above.

This adapter provides the following:

• Wrapper Angular components for all Forge components.
  • This allows you to use Forge components as if they were native Angular components.
  • Provides type safety for all custom element properties and events.
  • Auto-defines the custom element with the browser’s custom elements registry.
• Automatically provides ControlValueAccessor directives for native Angular integration with Forge’s form-associated elements.
• Exposes Angular providers for creating dynamic components such as dialogs, toasts, and popovers.
  • Ensures that the dynamic components are created within the Angular context (zone), and are properly destroyed when no longer needed.
  • To open a dialog programmatically, inject DialogService from @tylertech/forge-angular and call open() with your component. ToastService and PopoverService work the same way for toasts and popovers.

While the adapter is not required to use Forge with Angular, it is highly recommended to make the integration easier.

You can view source code for the Angular adapter on GitHub

Installation

To use Forge in your Angular application, install the following packages from npm:

npm install @tylertech/forge @tylertech/forge-angular

Now that you have Forge and the Angular adapter installed, let’s add the rest of the setup to your Angular application.

Loading the Tyler font

Edit your index.html file and add the following <link> tag to the <head> section load the Tyler font:

<link rel="stylesheet" href="https://cdn.forge.tylertech.com/v1/css/tyler-font.css" />

This will configure the default font family for your application, and load the required font weights and styles.

Importing Components

To use Forge components in your Angular application, you will need to import component modules from the @tylertech/forge-angular package for each component you want to use.

With Angular modules:

import { ForgeButtonModule } from '@tylertech/forge-angular';

@NgModule({
  imports: [ForgeButtonModule]
})
export class MyModule {}

With standalone Angular components:

import { ForgeButtonModule } from '@tylertech/forge-angular';

@Component({
  standalone: true,
  selector: 'app-my-component',
  template: '<forge-button>Click me</forge-button>',
  imports: [ForgeButtonModule]
})
export class MyComponent {}

Components that are only available through their own subpath import (such as user-profile, which isn’t included in the root @tylertech/forge import) have Angular modules too, for example ForgeUserProfileModule.

Importing Styles

Forge does not require any global styles (with one exception noted below) because the custom elements encapsulate their styles. However, there are some global styles that you may want to include in your application for your own use and tight integration with the Forge theming, typography, and token system.

To include any of these styles, you can import them from the @tylertech/forge package:

Typography

The forge-typography.css stylesheet provides a set of CSS classes that can be used to apply font styles to text content within your app.

@use '@tylertech/forge/dist/typography/forge-typography';

Theme

The forge-theme.css stylesheet provides a set of CSS variables that define the colors used throughout the design system.

@use '@tylertech/forge/dist/theme/forge-theme';

The tokens are all defined at the :root selector on your <html> element, so you can use them in your stylesheets like this:

.my-custom-class {
  background-color: var(--forge-theme-primary);
  color: var(--forge-theme-on-primary);
}

If you plan on allow for theme switching in your application, such as loading the Forge dark theme, it’s important that you do not use any hard-coded colors in your stylesheets. Instead, use the Forge theme tokens to ensure that your application’s colors are consistent and are automatically themed properly when the theme changes.

See the Theming guide for more information on theming with Forge and loading the built-in dark theme.

Tokens

The forge-tokens.css stylesheet provides a set of CSS variables that define various utility tokens used throughout the design system such as spacing, border, animation, elevation… etc.

@use '@tylertech/forge/dist/forge-tokens';

This will allow you to use the tokens in your stylesheets like this:

.my-custom-class {
  padding: var(--forge-spacing-medium);
  border-radius: var(--forge-shape-medium);
  box-shadow: var(--forge-elevation-4);
  border: var(--forge-border-thin) solid var(--forge-theme-outline);
  transition: background-color var(--forge-animation-duration-short4) var(--forge-animation-easing-standard);
}

You can see all tokens available on the page under the :root selector on your <html> element.

See the Design Tokens documentation for more information on the available tokens.

Global Component Styles

All Forge components are designed to be used as standalone elements, and they encapsulate their styles. However, the one exception to this is the <forge-table> component, which requires some global styles to be included in your application to ensure proper rendering.

To include the global styles for the <forge-table> component, you can import the following stylesheet:

@use '@tylertech/forge/dist/table/forge-table';

If you’re loading this stylesheet within a component that uses Angular’s style encapsulation you will need to use ::ng-deep to apply the styles globally:

::ng-deep {
  @import '@tylertech/forge/dist/table/forge-table';
}

Using ::ng-deep just ensures that the selectors in this stylesheet aren’t scoped to the component and are applied globally when this component is used.

All

The forge.css stylesheet includes everything listed below for convenience.

@use '@tylertech/forge/dist/forge';

Using Icons

Using icons within your Angular application is as simple as using the <forge-icon> component. You can import the ForgeIconModule from the @tylertech/forge-angular package to use the icon component.

import { ForgeIconModule } from '@tylertech/forge-angular';

@NgModule({
  imports: [ForgeIconModule]
})
export class MyModule {}

Icons are defined within the Forge IconRegistry:

import { IconRegistry } from '@tylertech/forge';
import { tylIconPerson } from '@tylertech/tyler-icons';

@Component({
  selector: 'app-my-component',
  template: '<forge-icon name="person"></forge-icon>'
})
export class MyComponent {
  constructor() {
    IconRegistry.define([tylIconPerson]);
  }
}

To learn more about icons see the Icons documentation.

Important: You must define your icons either within the constructor of your component/module, or within a static initialization block to ensure that when a production build of your application is created the icons are not tree-shaken away.

Events

Angular uses parentheses () to bind to events. When using Forge components, you will use the same syntax for its custom events.

<!-- Using standard built-in browser events -->
<forge-button (click)="onClick($event)">Click me</forge-button>

<!-- Using custom events -->
<forge-slider (forge-slider-change)="onSliderChange($event)"></forge-slider>

For CustomEvent types, some of these events will contain a detail property that contains the event data. You can access this data in your event handler like this:

onSliderChange(event: CustomEvent<ISliderChangeEventData>) {
  console.log(event.detail);
}

Properties vs Attributes

When viewing the API details for Forge components, you’ll notice that there are both “properties” (camelCase) and “attributes” (snake-case) listed. This is because HTML elements can have both properties and attributes, and they are not the same thing. Properties are used to set values on the component instance, while attributes are typically used to initialize values on the DOM element.

When using Angular with Forge, you’ll most commonly use the square bracket syntax [] to bind values to an element. Angular will set values on the component instance using the property name.

For example, to set a value property on an element, you would use the following syntax:

<forge-element [value]="myValue"></forge-element>

To initialize the value of the element using an attribute, you would use the following syntax:

<forge-element value="5"></forge-element>

You can also force the binding to always use the attribute if you need to:

<forge-element [attr.value]="myValue"></forge-element>

Forge components will observe changes to HTML attributes, but keep in mind that attribute values are always passed as strings to the component. The component will try to coerce primitive values such as booleans and numbers, but more complex values such as objects or arrays will not be coerced and you should only use properties to pass these values.

CUSTOM_ELEMENTS_SCHEMA

While not recommended, if you prefer not to use the adapter, you can easily disable the Angular compiler from throwing errors by adding the CUSTOM_ELEMENTS_SCHEMA to your component or module’s schemas array:

import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}

This is a quicker and easier way to get started with Forge components in your Angular application, but keep in mind that you will lose some of the type safety and integration benefits that the adapter provides.

If you’re interested in pushing the Angular team along to help improve the support for custom elements, please consider up voting or chiming in on the Angular issue that is tracking this feature request.