🅰️ Beam Web Components Angular

Angular wrapper components for the Beam Design System web components. These wrappers provide type-safe Angular bindings with signal-based inputs/outputs, OnPush change detection, and full support for content projection.

🔖 Table of Contents

1. ✨ Features
2. 💻 Installation
3. 🚀 Quick Start
4. 🛠️ Usage
5. 🌳 Tree-Shaking & Optimization
6. 🔧 Troubleshooting
7. 📚 Documentation
8. 🤝 Contributing
9. 📄 License

Features

• Type Safety - Full TypeScript support with properly typed signal inputs and outputs
• Signal-Based API - Built with Angular's modern input() and output() signal APIs
• OnPush Compatible - All components use ChangeDetectionStrategy.OnPush for optimal performance
• Standalone Components - Modern Angular standalone components, no NgModule required
• Tree-Shakable - Secondary entry points ensure you only bundle what you use
• Content Projection - Seamless slot-to-<ng-content> mapping for flexible composition
• Boolean Attribute Handling - Automatic booleanAttribute transforms for boolean props
• Angular 17+ - Built for modern Angular applications

Installation

npm install @viasat/beam-web-components-angular

yarn add @viasat/beam-web-components-angular

pnpm add @viasat/beam-web-components-angular

💡 Note: This package requires @angular/core >= 17.3.0, @viasat/beam-web-components, @viasat/beam-shared, and @floating-ui/dom as peer dependencies.

Quick Start

1. Import Required Styles

Import the base tokens and fonts at the root of your application:

// styles.scss or main.ts
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-fonts/styles.css';

2. Use Components

import { Component } from '@angular/core';
import { AlertComponent } from '@viasat/beam-web-components-angular/alert';

@Component({
  selector: 'app-my-component',
  standalone: true,
  imports: [AlertComponent],
  template: `
    <bm-ng-alert
      heading="Welcome!"
      body="This is a Beam alert in Angular."
      appearance="positive"
      [dismissible]="true"
      (bmDismiss)="onDismiss($event)"
    />
  `,
})
export class MyComponent {
  onDismiss(event: CustomEvent): void {
    console.log('Alert dismissed');
  }
}

💡 Note: Components are imported from secondary entry points (e.g. @viasat/beam-web-components-angular/alert), not from the package root. This enables optimal tree-shaking.

Usage

Importing Components

Each component is available from its own secondary entry point:

// ✅ Import from secondary entry points
import { AlertComponent } from '@viasat/beam-web-components-angular/alert';
import { ButtonComponent } from '@viasat/beam-web-components-angular/button';
import { AccordionComponent } from '@viasat/beam-web-components-angular/accordion';

Property Binding

Properties use Angular's signal-based input() API. Bind to them like any Angular input:

import { Component } from '@angular/core';
import { ButtonComponent } from '@viasat/beam-web-components-angular/button';

@Component({
  selector: 'app-button-demo',
  standalone: true,
  imports: [ButtonComponent],
  template: `
    <bm-ng-button appearance="primary" size="lg" [disabled]="isDisabled">
      Click me
    </bm-ng-button>
  `,
})
export class ButtonDemoComponent {
  isDisabled = false;
}

Event Binding

Events are exposed as Angular output() signals. All custom events are prefixed with bm:

import { Component } from '@angular/core';
import { AlertComponent } from '@viasat/beam-web-components-angular/alert';

@Component({
  selector: 'app-alert-demo',
  standalone: true,
  imports: [AlertComponent],
  template: `
    <bm-ng-alert
      heading="Dismissible Alert"
      appearance="warning"
      [dismissible]="true"
      (bmDismiss)="onDismiss($event)"
    >
      This alert can be dismissed.
    </bm-ng-alert>
  `,
})
export class AlertDemoComponent {
  onDismiss(event: CustomEvent): void {
    console.log('Alert dismissed', event);
  }
}

Boolean Attributes

Boolean properties automatically use Angular's booleanAttribute transform, so you can set them as HTML attributes or bind them:

<!-- As an attribute (sets to true) -->
<bm-ng-alert dismissible heading="Alert" />

<!-- As a binding -->
<bm-ng-alert [dismissible]="isDismissible" heading="Alert" />

Using Slots

Web component slots work seamlessly with Angular content projection:

@Component({
  template: `
    <bm-ng-alert appearance="infoPrimary" [dismissible]="true">
      <span slot="heading">Custom Heading</span>
      <span slot="actions">
        <button>Take Action</button>
      </span>
    </bm-ng-alert>
  `,
})

Composing Components

import { Component } from '@angular/core';
import { AccordionGroupComponent } from '@viasat/beam-web-components-angular/accordion-group';
import { AccordionComponent } from '@viasat/beam-web-components-angular/accordion';

@Component({
  selector: 'app-accordion-demo',
  standalone: true,
  imports: [AccordionGroupComponent, AccordionComponent],
  template: `
    <bm-ng-accordion-group [singleExpand]="true">
      <bm-ng-accordion heading="Section 1" [defaultOpen]="true">
        Content for section 1
      </bm-ng-accordion>
      <bm-ng-accordion heading="Section 2">
        Content for section 2
      </bm-ng-accordion>
    </bm-ng-accordion-group>
  `,
})
export class AccordionDemoComponent {}

Tree-Shaking & Optimization

How It Works

Each component is published as a secondary entry point via ng-packagr. This means Angular's build system only includes the components you actually import, unused components are completely excluded from your bundle.

• Secondary Entry Points - Each component has its own ng-package.json, enabling per-component bundling
• Side-Effect Imports - Only the underlying web component JS for imported wrappers is included
• Zero Config - Angular CLI, Webpack, and esbuild all respect entry point boundaries automatically

// ✅ Recommended: Import from secondary entry points
import { AlertComponent } from '@viasat/beam-web-components-angular/alert';
import { ButtonComponent } from '@viasat/beam-web-components-angular/button';

⚠️ Note: The primary entry point (@viasat/beam-web-components-angular) does not re-export components. Always import from secondary entry points.

Troubleshooting

Components not rendering

Make sure you've imported the required base styles at the root of your application:

import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-fonts/styles.css';

'bm-ng-*' is not a known element

Add CUSTOM_ELEMENTS_SCHEMA to your component's schemas if you're using the raw web components alongside the wrappers. The wrapper components already include this schema, this error typically means you're referencing a web component tag that doesn't have a corresponding wrapper import.

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

@Component({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  // ...
})

Boolean attributes not working as expected

Boolean props use Angular's booleanAttribute transform. Pass true/false via binding, or use the attribute name without a value to set it to true:

<!-- These are equivalent -->
<bm-ng-alert [dismissible]="true" />
<bm-ng-alert dismissible />

If you encounter a bug, please file an issue in the Beam Design System issue tracker with your Angular version, package version, and steps to reproduce.

Documentation

Storybook

Explore component examples and API documentation:

📖 Beam Web Components Storybook

The Angular Guide provides comprehensive documentation on:

• Using pre-built Angular wrappers
• Direct web component usage in Angular
• Creating custom wrappers
• Best practices and patterns

Additional Resources

• Web Components - @viasat/beam-web-components
• Design Tokens - @viasat/beam-tokens
• Icon Library - @viasat/beam-icons
• Typography - @viasat/beam-fonts

Contributing

This package is part of the Beam Design System monorepo. For contribution guidelines, please refer to the main repository documentation.

Regenerating Wrappers

The Angular wrappers are auto-generated from the web components' Custom Elements Manifest. To regenerate after web component changes:

npx nx run web-components-angular:generate

Adding New Components

1. Ensure the web component has customElement: true in its Custom Elements Manifest
2. Verify the component is not in the EXCLUDE_COMPONENTS list in scripts/config.ts
3. Run the generator: npx nx run web-components-angular:generate
4. Review the generated files in src/lib/<component-name>/

License

MIT © Viasat