@viasat/beam-web-components

v2.1.1

Published

6 days ago

Framework-agnostic web components for the Beam Design System built with Lit, compatible with Angular, Vue, Svelte, and vanilla JavaScript

0High
0Medium
0Low

web-components custom-elements design-system beam lit angular vue svelte framework-agnostic

🎨 Beam Web Component

Beam web components is a library of web components for the Beam Design System. These components are built using Lit (a web components library created by Google) and are designed to be used in any web project. 🌎

Our library includes support for various formats and stacks to suit different needs, such as:

Frameworks

Vanilla JS support: Incorporate our components in Vanilla JS projects, providing a versatile and adaptable solution for your project.
Angular support: Utilize our components in Angular projects, ensuring compatibility with your existing stack.

Importing

Importing from NPM: Easily import and utilize our package directly from NPM, ensuring a seamless integration into your project.
Importing locally: Download and use our package locally, providing a flexible and customizable approach for your project.

🔖 Table of Contents

⬇️ Installation

📦 NPM

The easiest and most straightforward way to install @viasat/beam-web-components is via NPM.

1. Install the package

npm install @viasat/beam-web-components

yarn add @viasat/beam-web-components

pnpm add @viasat/beam-web-components

2. Import and use the components

ℹ️ Import the fonts and tokens at the root of your application and import each component per page to ensure bundlers like webpack and rollup can optimally code split and tree shake the components.

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

// my-page.js
import '@viasat/beam-web-components/Alert';

💻 Local Installation (Without npm)

For airgapped (no internet access) environments or when you need to vendor the files directly without a package manager, you can use the pre-bundled web components build.

⚠️ Note: This approach is for special scenarios only. If you have npm/artifactory access, use the NPM installation method instead - it's simpler and handles dependencies automatically.

1. Download the bundled package

Contact your Beam administrator or download directly from npm registry:

npm pack @viasat/beam-web-components

This downloads the package as beam-web-components-[VERSION].tgz. The bundled version includes all dependencies (lit, floating-ui, etc.) pre-compiled into the output.

2. Extract web-components to your project

mkdir -p vendor/@viasat/beam-web-components
tar -xvf beam-web-components-[VERSION].tgz -C vendor/@viasat/beam-web-components/ --strip-components=1

The bundled components are in the local/ directory.

3. Download and extract tokens and fonts

# Download and extract tokens
npm pack @viasat/beam-tokens
mkdir -p vendor/@viasat/beam-tokens
tar -xvf beam-tokens-[VERSION].tgz -C vendor/@viasat/beam-tokens/ --strip-components=1

# Download and extract fonts
npm pack @viasat/beam-fonts
mkdir -p vendor/@viasat/beam-fonts
tar -xvf beam-fonts-[VERSION].tgz -C vendor/@viasat/beam-fonts/ --strip-components=1

Expected Directory Structure:

vendor/
└── @viasat/
    ├── beam-web-components/
    │   ├── local/          # Bundled components (use these)
    │   │   ├── Alert/
    │   │   │   └── Alert.js
    │   │   ├── Button/
    │   │   ├── Badge/
    │   │   ├── chunks/     # Shared code chunks
    │   │   └── ...
    │   └── package.json
    ├── tokens/
    │   └── tokens.css      # Design tokens CSS
    └── fonts/
        └── styles.css      # Font styles

4. Use in your HTML

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My Web Page</title>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <!-- Import Tokens -->
    <link rel="stylesheet" href="vendor/@viasat/beam-tokens/tokens.css" />

    <!-- Import Fonts -->
    <link rel="stylesheet" href="vendor/@viasat/beam-fonts/styles.css" />
  </head>
  <body>
    <!-- Use the component -->
    <bm-alert body="My alert message" header="Alert Title" dismissible></bm-alert>

    <!-- Import component from local build (place at end of body) -->
    <script
      type="module"
      src="vendor/@viasat/beam-web-components/local/Alert/Alert.js"
    ></script>
  </body>
</html>

Dependencies

The bundled local build includes all JavaScript dependencies pre-compiled:

Bundled Dependencies (included in the local build):

✅ lit - Web components framework
✅ @lit/context - Context API for Lit
✅ @floating-ui/dom & @floating-ui/utils - Positioning utilities
✅ clsx - Class name utility
✅ @viasat/beam-shared, @viasat/beam-styles, @viasat/beam-icons - Beam internal packages

Required Packages (must be downloaded separately - see step 3):

@viasat/beam-tokens - Design tokens (CSS variables)
@viasat/beam-fonts - Typography assets

🧠 VS Code IntelliSense Setup

Enable intelligent autocomplete in VS Code for Beam web components, including component names, attributes, and their valid values.

1. Configure VS Code Settings

Add the custom data files to your workspace settings (.vscode/settings.json):

For NPM installations:

{
  "html.customData": [
    "node_modules/@viasat/beam-web-components/vscode.html-custom-data.json"
  ],
  "css.customData": [
    "node_modules/@viasat/beam-web-components/vscode.css-custom-data.json"
  ]
}

For local/vendored installations:

{
  "html.customData": [
    "vendor/@viasat/beam-web-components/vscode.html-custom-data.json"
  ],
  "css.customData": [
    "vendor/@viasat/beam-web-components/vscode.css-custom-data.json"
  ]
}

2. Reload VS Code

Reload your VS Code window to activate IntelliSense:

Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Type "Reload Window" and press Enter

What You Get

Component Autocomplete:

Type <bm- to see all available Beam components
See component descriptions while typing

Attribute Suggestions:

Get autocomplete for all component attributes
See valid values for each attribute (e.g., appearance="infoPrimary | infoSecondary | positive | warning | negative")
View attribute descriptions and types

Updating IntelliSense

When you upgrade @viasat/beam-web-components, the custom data files are automatically updated in node_modules. Simply reload VS Code to pick up the latest component definitions:

Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Type "Reload Window" and press Enter

🛠️ Usage

Explore our component library with live examples and API documentation in our Storybook.

Component Attributes & Properties

Web components accept attributes in HTML and properties via JavaScript:

<!-- Using attributes -->
<bm-button appearance="primary" size="lg" disabled>Button Text</bm-button>

<script type="module">
  import '@viasat/beam-web-components/Button';

  // Using properties
  const button = document.querySelector('bm-button');
  button.appearance = 'secondary';
  button.disabled = false;
</script>

Component Events

Listen for custom events using standard DOM event listeners:

import '@viasat/beam-web-components/Alert';

const alert = document.querySelector('bm-alert');
alert.addEventListener('bm-dismiss', event => {
  console.log('Alert was dismissed');
});

Component Slots

Many components support content slots for flexible composition:

<bm-alert appearance="infoPrimary" dismissible>
  <div slot="header">Custom Alert Header</div>
  <div slot="body">
    <p>This is custom alert content using slots.</p>
    <p>You can add any HTML content here!</p>
  </div>
</bm-alert>

Tree-shaking & Optimization

Import only the components you need for optimal bundle size:

// ✅ Recommended: Import individual components
import '@viasat/beam-web-components/Alert';
import '@viasat/beam-web-components/Button';

// ⚠️ Avoid: Importing the entire library loads ALL components
import '@viasat/beam-web-components';

Framework Integration

Angular

// In your component
import '@viasat/beam-web-components/Button';

// In your template
<bm-button appearance="primary" (click)="handleClick()">
  Angular Button
</bm-button>

ℹ️ For advanced Angular integration including wrappers, two-way binding, and best practices, see the Angular Guide.

Theming

Apply themes using CSS classes on your root element:

<!-- Light theme -->
<div class="bm-light">
  <bm-button>Light Theme Button</bm-button>
</div>

<!-- Dark theme -->
<div class="bm-dark">
  <bm-button>Dark Theme Button</bm-button>
</div>

<!-- Accent theme -->
<div class="bm-light bm-blue">
  <bm-button>Blue Accent Button</bm-button>
</div>

ℹ️ For advanced theming documentation and use cases, see the Theming Guide.

Accessibility

All components are built with accessibility in mind:

ARIA Support - Proper ARIA labels and roles
Keyboard Navigation - Full keyboard support
Screen Reader Support - Semantic markup and announcements
Focus Management - Proper focus handling and trapping

Documentation

Storybook

Explore our comprehensive component library with live examples and API documentation:

📖 Beam Web Components Storybook

Component API

Each component includes:

Props Documentation - Complete TypeScript definitions
Usage Examples - Common patterns and configurations
Accessibility Notes - ARIA labels, keyboard navigation, screen reader support
Theming Options - Available variants and customization points

Additional Resources

Design Tokens - @viasat/beam-tokens
Icon Library - @viasat/beam-icons
Typography - @viasat/beam-fonts