# ⚛️ 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 1. [✨ Features](#features) 2. [💻 Installation](#installation) 3. [🚀 Quick Start](#quick-start) 4. [🛠️ Usage](#usage) 5. [🎨 Theming](#theming) 6. [📦 Tree-Shaking & Optimization](#tree-shaking--optimization) 7. [📚 Documentation](#documentation) ## 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 ```bash npm install @viasat/beam-react ``` ```bash yarn add @viasat/beam-react ``` ```bash 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 ```tsx 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 ( Welcome to Beam ); } ``` ### Next.js Application #### 1. Copy Fonts to Public Directory Add a `postinstall` script to your `package.json`: ```json { "scripts": { "postinstall": "cp -R node_modules/@viasat/beam-fonts/assets public/fonts" } } ``` Run the script: ```bash npm run postinstall ``` #### 2. Import Styles in Your Root Layout ```tsx // 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 ( {children} ); } ``` #### 3. Use Beam Components ```tsx // app/page.tsx import { Button } from '@viasat/beam-react/Button'; export default function HomePage() { return ; } ``` ## Usage ### Importing Components Beam supports multiple import patterns, all optimized for tree-shaking: ```tsx // 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: ```ts // 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](https://react.beam.viasat.com/?path=/docs/concepts-theming--docs)** ### Quick Example ```tsx import { BeamThemeProvider } from '@viasat/beam-react'; import '@viasat/beam-tokens/styles.css'; function App() { return ( {/* All components automatically use the theme */} ); } ``` ### Next.js Theming When using `BeamThemeProvider` in Next.js, you'll need to: 1. **Mark the provider as a client component** with `'use client'` 2. **Add `suppressHydrationWarning` to your `` tag** to prevent hydration warnings (the theme provider updates this element) ```tsx // 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 ( {children} ); } ``` ```tsx // app/clientProviders.tsx 'use client'; import { BeamThemeProvider } from '@viasat/beam-react'; export default function ClientProviders({ children, }: { children: React.ReactNode; }) { return {children}; } ``` > **📖 For complete Next.js setup, detailed information on accent themes, brand themes, dynamic theme switching, and advanced theming patterns, see the [theming documentation](https://react.beam.viasat.com/?path=/docs/concepts-theming--docs).** ## 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 ```tsx // 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](https://react.beam.viasat.com/)** #### 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](https://www.npmjs.com/package/@viasat/beam-tokens) - **Icon Library** - [@viasat/beam-icons](https://www.npmjs.com/package/@viasat/beam-icons) - **Typography** - [@viasat/beam-fonts](https://www.npmjs.com/package/@viasat/beam-fonts) ## Contributing This package is part of the Beam Design System monorepo. For contribution guidelines, please refer to the main repository documentation. ## License MIT © Viasat