@viasat/beam-react

v2.1.1

Published

6 days ago

React component library for the Beam design system

0High
0Medium
0Low

react components design-system beam ui component-library

⚛️ Beam React

A headless, token-driven React component library built for modern web applications. Beam React provides scalable, accessible components with first-class support for theming, tree-shaking, and cross-platform development.

🔖 Table of Contents

Features

50+ Production-Ready Components - From basic buttons to complex data visualizations
Fully Accessible - WCAG 2.1 AA compliant with comprehensive ARIA support
Token-Driven Design - Built on @viasat/beam-tokens for consistent, themeable styling
Tree-Shakable - Optimized bundle sizes with automatic CSS code-splitting
TypeScript First - Complete type definitions and IntelliSense support
Framework Agnostic Styling - Works with any CSS approach (CSS Modules, Tailwind, CSS-in-JS)
Dark Mode Ready - Built-in support for light and dark themes
Next.js Optimized - Server component compatible with App Router support

Installation

npm install @viasat/beam-react

yarn add @viasat/beam-react

pnpm add @viasat/beam-react

💡 Note: When you install @viasat/beam-react, it automatically includes all necessary dependencies such as @viasat/beam-icons, @viasat/beam-tokens, and @viasat/beam-fonts.

Quick Start

Standard React Application

import { Button } from '@viasat/beam-react/Button';
import { Text } from '@viasat/beam-react/Text';
import { Box } from '@viasat/beam-react/Box';

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

export default function App() {
  return (
    <Box>
      <Text variant="heading-lg">Welcome to Beam</Text>
      <Button onClick={() => alert('Hello!')}>Get Started</Button>
    </Box>
  );
}

Next.js Application

1. Copy Fonts to Public Directory

Add a postinstall script to your package.json:

{
  "scripts": {
    "postinstall": "cp -R node_modules/@viasat/beam-fonts/assets public/fonts"
  }
}

Run the script:

npm run postinstall

2. Import Styles in Your Root Layout

// app/layout.tsx
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-fonts/styles.nextjs.css'; // Use Next.js-specific font import

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

3. Use Beam Components

// app/page.tsx
import { Button } from '@viasat/beam-react/Button';

export default function HomePage() {
  return <Button appearance="accent">Click me!</Button>;
}

Usage

Importing Components

Beam supports multiple import patterns, all optimized for tree-shaking:

// Root-level import
import { Box, Button, Text } from '@viasat/beam-react';

// Direct component import (recommended)
import { Box } from '@viasat/beam-react/Box';
import { Button } from '@viasat/beam-react/Button';
import { Text } from '@viasat/beam-react/Text';

Both approaches are fully tree-shakable and will only include the components you use.

Required Styles

Import the base stylesheet in your application entry point:

// For standard React apps
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-fonts/styles.css';

// For Next.js apps
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-fonts/styles.nextjs.css';

Theming

Beam React components are built on top of @viasat/beam-tokens, providing powerful theming capabilities including light/dark modes, accent theming, product theming (enterprise/consumer), and brand-specific customization. All components automatically respond to theme context without any additional configuration.

📖 View Complete Theming Guide

Quick Example

import { BeamThemeProvider } from '@viasat/beam-react';
import '@viasat/beam-tokens/styles.css';

function App() {
  return (
    <BeamThemeProvider
      defaultTheme={{ mode: 'light', accent: 'teal', productType: 'enterprise' }}
    >
      {/* All components automatically use the theme */}
    </BeamThemeProvider>
  );
}

Next.js Theming

When using BeamThemeProvider in Next.js, you'll need to:

Mark the provider as a client component with 'use client'
Add suppressHydrationWarning to your <html> tag to prevent hydration warnings (the theme provider updates this element)

// app/layout.tsx
import ClientProviders from './clientProviders';
import '@viasat/beam-tokens/styles.css';
import '@viasat/beam-fonts/styles.nextjs.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ClientProviders>{children}</ClientProviders>
      </body>
    </html>
  );
}

// app/clientProviders.tsx
'use client';
import { BeamThemeProvider } from '@viasat/beam-react';

export default function ClientProviders({
  children,
}: {
  children: React.ReactNode;
}) {
  return <BeamThemeProvider>{children}</BeamThemeProvider>;
}

📖 For complete Next.js setup, detailed information on accent themes, brand themes, dynamic theme switching, and advanced theming patterns, see the theming documentation.

Tree-Shaking & Optimization

Beam 3 is designed for optimal performance with zero-config tree-shaking:

How It Works

Component Styles Are Split - Each component includes only the CSS it needs
ESM-Based Tree-Shaking - Only imported components are included in your bundle
Automatic CSS Code-Splitting - Vite/Webpack automatically split CSS per component
Optimized Side Effects - CSS files are properly marked, ensuring safe tree-shaking of JS while preserving styles

Bundle Size Examples

// Only Button's JS + CSS is included
import { Button } from '@viasat/beam-react/Button';

// Only Button and Box's JS + CSS is included
import { Button } from '@viasat/beam-react/Button';
import { Box } from '@viasat/beam-react/Box';

// Root-level imports work too (same bundle size as above)
import { Button, Box } from '@viasat/beam-react';

Build Tool Compatibility

Beam works seamlessly with:

✅ Vite - Full support with automatic optimization
✅ Webpack 5 - Modern tree-shaking and code-splitting
✅ Next.js - App Router and Pages Router compatible
✅ Rollup - ESM-first bundling
✅ esbuild - Ultra-fast builds with tree-shaking

Documentation

Storybook

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

📖 Beam React 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

Contributing

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