@beam-ui/components

v1.4.0

Published

22 days ago

Pure Web Components for the Beam UI Design System

0High
0Medium
0Low

leo_alekseev

jordang-tatari

tatarian

beam-ui design-system web-components custom-elements

Beam UI Components

Pure Web Components for the Beam UI Design System.

Installation

Option 1: npm/yarn

For applications with a build process:

npm install @beam-ui/components
# or
yarn add @beam-ui/components

Note: @beam-ui/design-tokens is automatically installed as a dependency.

Option 2: CDN via UNPKG or jsDelivr (Zero Configuration)

For server-side rendered HTML, static sites, or environments where build process is not available.

The package provides a self-contained bundle for CDN usage with design tokens automatically injected - no CSS imports needed! (Works with both UNPKG and jsDelivr.)

Import All Components (Single File):

<script type="module">
  import {BeamButton, BeamInput, BeamLoadingSpinner, BeamAnchorLink} from 'https://unpkg.com/@beam-ui/components@latest/bundle/index.js';
  // or
  import {BeamButton, BeamInput, BeamLoadingSpinner, BeamAnchorLink} from 'https://cdn.jsdelivr.net/npm/@beam-ui/components@latest/+esm';
</script>

💡 Use Cases for CDN:

Server-side templating (PHP, Ruby, Python, etc.)
Static HTML sites without build tools
Quick prototypes and demos
CodePen/JSFiddle examples
Documentation and tutorials

⚡ Performance Benefits:

Zero configuration - no CSS imports required
Single HTTP request for all components (no dependency waterfall)
Self-contained - design tokens automatically injected when needed
Selective token injection - only design tokens actually used by the component
Zero-overhead optimization - no DOM operations when no tokens needed
Minified and optimized by Vite

⚠️ For Production: Pin to a specific version instead of using @latest:

<script type="module">
  import {BeamButton, BeamInput, BeamLoadingSpinner, BeamAnchorLink} from 'https://unpkg.com/@beam-ui/[email protected]/bundle/index.js';
  // or
  import {BeamButton, BeamInput, BeamLoadingSpinner, BeamAnchorLink} from 'https://cdn.jsdelivr.net/npm/@beam-ui/[email protected]/+esm';
</script>

Usage

Import All Components

import '@beam-ui/components';

Import Individual Components (Recommended)

import '@beam-ui/components/button';
import '@beam-ui/components/input';
import '@beam-ui/components/loading-spinner';
import '@beam-ui/components/anchor-link';

Using in HTML (with npm)

Your bundler (Webpack, Vite, etc.) automatically handles design token CSS imports:

<!DOCTYPE html>
<html>
<body>
  <!-- Use components -->
  <beam-button>Click me</beam-button>
  <beam-input label="Email" name="email" type="email"></beam-input>
  <beam-loading-spinner size="lg"></beam-loading-spinner>
  <beam-anchor-link href="/about">About</beam-anchor-link>

  <script type="module">
    // Design tokens CSS automatically imported by bundler
    import '@beam-ui/components';
  </script>
</body>
</html>

Using in HTML (with CDN)

Perfect for server-side templates (PHP, Django, Rails, etc.) - no CSS imports needed:

<!DOCTYPE html>
<html>
<body>
  <!-- Use components -->
  <beam-button>Click me</beam-button>
  <beam-input label="Email" name="email" type="email"></beam-input>
  <beam-loading-spinner size="lg"></beam-loading-spinner>
  <beam-anchor-link href="/about" with-icon>About</beam-anchor-link>

  <script type="module">
    import 'https://unpkg.com/@beam-ui/[email protected]/bundle/index.js';
    // or
    import 'https://cdn.jsdelivr.net/npm/@beam-ui/[email protected]/+esm';
  </script>
</body>
</html>

npm vs CDN: When to Use Each

| Method | Best For | Setup | Performance | |--------|----------|-------|-------------| | npm + Bundler | Apps with build tools (React, Vue, etc.) | CSS auto-imported by bundler | Smaller final bundle (tree-shaking) | | CDN Bundles | Server-side templates, static sites | Zero config - tokens auto-injected | Single HTTP request |

Components

Loading Spinner

An accessible, animated loading spinner with customizable size and color.

Element: <beam-loading-spinner>
Sizes: xs (default), sm, md, lg
Accessibility: Respects prefers-reduced-motion, ARIA-ready
Documentation: Loading Spinner Docs

<beam-loading-spinner size="md"></beam-loading-spinner>

Button

A versatile, accessible button with multiple variants, sizes, and states. Supports loading states with an integrated spinner.

Element: <beam-button>
Variants: primary (default), secondary, tertiary, danger, danger-secondary
Sizes: sm, md, lg (default)
States: disabled, loading
Form Support: Form-associated (type="submit", type="reset")
Documentation: Button Docs

<beam-button variant="primary">Click me</beam-button>
<beam-button variant="secondary" size="md">Cancel</beam-button>
<beam-button loading>Saving...</beam-button>

Input

A text input component with built-in label, error/warning messages, clearable button, and full form participation.

Element: <beam-input>
Types: text (default), email, number, tel, url, password, search
States: disabled, readonly, error, warning, clearable
Form Support: Form-associated via ElementInternals
Documentation: Input Docs

<beam-input label="Email" name="email" type="email" required></beam-input>
<beam-input label="Search" clearable></beam-input>
<beam-input label="Budget" value="500" warning="Below minimum"></beam-input>

Anchor Link

An anchor element component with optional external link icon. Follows web standards and accessibility best practices for links.

Element: <beam-anchor-link>
Attributes: href (required), with-icon, target, rel, download
Security: Auto-adds rel="noopener noreferrer" for target="_blank"
Accessibility: Native link semantics, keyboard navigation, screen reader support
Documentation: Anchor Link Docs

<beam-anchor-link href="/about">About</beam-anchor-link>
<beam-anchor-link href="https://example.com" with-icon>External Link</beam-anchor-link>
<beam-anchor-link href="https://docs.example.com" target="_blank" with-icon>Documentation</beam-anchor-link>

Related Packages

@beam-ui/design-tokens - Design system tokens

License

MIT License - see LICENSE file for details