DOCSEARCHbyAlgolia
Submit Docs

border-beam

repository·main·Indexed 22 days ago

https://github.com/jakubantalik/border-beam

A lightweight library providing animated border effects, such as traveling beams and breathing glows, for UI elements. It includes the core React package (v1.4.0), a React Native implementation (border-beam-native) using Skia and Reanimated, and a SwiftUI port (BorderBeamKit) utilizing Metal shaders for iOS 17+ and macOS 14+.

Tokens
13.6K
Snippets
45
Records
68
Agent score
77%

What's inside border-beam

  1. Overview of the border-beam porting strategy

    main

    The border-beam project is being ported from Web to iOS (SwiftUI) and React Native to provide high-fidelity, hardware-accelerated visual effects across platforms.

    Core Design Principles:

    • Platform-neutral specification: All visual data (gradient palettes, pulse geometry, oscillator tables, and mask geometry) is stored in a central spec/beam-spec.json. Both iOS and React Native ports consume code generated from this spec to ensure visual parity.
    • Hardware Acceleration:
      • iOS: Uses SwiftUI with Metal shaders via Canvas and Shader (layerEffect).
      • React Native: Uses @shopify/react-native-skia and react-native-reanimated to run SkSL shaders and UI-thread animation loops.
    • Visual Fidelity: The goal is pixel-close parity with the web version, using the web demo as the visual reference. This includes reproducing specific CSS filter behaviors (like hue-rotate matrices) and complex gradient falloffs in shaders.

  3. Build BorderBeamKit using xcodebuild

    main

    Building the project requires a full Xcode installation because the .metal shaders must be compiled by Xcode's build system. Command Line Tools alone are insufficient for building the shaders.

    You can build without using sudo xcode-select by pointing the DEVELOPER_DIR environment variable to your Xcode installation path.

    DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -scheme BorderBeamKit -destination 'platform=macOS' build

  4. Quick start with BorderBeam

    main

    Wrap your content with the BorderBeam component. It automatically detects the border-radius of the first child element and overlays the animated effect. The effect layers use pointer-events: none, so they won't interfere with user interactions with your content.

    import { BorderBeam } from 'border-beam';

function App() {
  return (
    <BorderBeam>
      <div style={{ padding: 32, borderRadius: 16, background: '#1d1d1d' }}>
        Your content here
      </div>
    </BorderBeam>
  );
}

  5. Sync visual specifications from the web library

    main

    The visual data (palettes, presets, oscillator tables) is not hard-coded in Swift; it is decoded from beam-spec.json. If the web library is updated, you must regenerate and copy the spec file to the iOS project to maintain visual parity.

    Run the following commands from the web library context:

    1. Generate the spec: npm run spec
    2. Copy to iOS: cp spec/beam-spec.json ports/ios/BorderBeamKit/Sources/BorderBeamKit/Resources/
    npm run spec && cp spec/beam-spec.json ports/ios/BorderBeamKit/Sources/BorderBeamKit/Resources/

  7. Run the BorderBeamKit demo in the iOS Simulator

    main

    To run the demo app, use the provided run.sh script. This script generates the Xcode project, boots the simulator, builds, installs, and launches the app. The demo app allows you to interactively test all 5 types with pickers for color variant, theme, and active state.

    First-time setup requirements:

    1. Install xcodegen via Homebrew.
    2. Download the iOS platform via xcodebuild.

    Usage:

    • Run with default settings: ./run.sh
    • Run with a specific device: ./run.sh "iPhone 16e"
    # First-time setup
brew install xcodegen
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -downloadPlatform iOS

# Run the demo
ports/ios/BorderBeamDemo/run.sh "iPhone 16e"

  8. Use BorderBeamKit in SwiftUI

    main

    BorderBeamKit is a SwiftUI port of the border-beam web library, providing animated borders using Metal shaders. It supports iOS 17+ and macOS 14+. You can use it either as a wrapper view or as a view modifier.

    Available properties that mirror the web implementation include:

    • size: Preset sizes (sm, md, line, pulse-outside, pulse-inner).
    • colorVariant: Color presets (e.g., .ocean, .colorful).
    • theme: Color scheme (.auto follows the system).
    • staticColors: Custom color arrays.
    • duration: Animation speed.
    • active: Controls visibility (fades in/out with onActivate / onDeactivate callbacks).
    • borderRadius: Explicit corner radius (falls back to size preset if not provided).
    • brightness, saturation, hueRange, strength: Visual tuning parameters.
    import BorderBeamKit

// Option 1: As a wrapper view
BorderBeam(size: .md, colorVariant: .ocean, theme: .auto) {
    Card()
}

// Option 2: As a modifier
Card().borderBeam(.md, colorVariant: .colorful)

  9. Verify visual parity across platforms

    main

    To ensure pixel-close parity between the web, iOS, and React Native versions, a multi-stage automated verification process is used.

    iOS Parity Verification: Uses a headless snapshot harness (ports/ios/BorderBeamKit/snapshot.sh) that renders all 40 combinations (5 types × 4 variants × 2 themes) using ImageRenderer.

    • Determinism: Uses an internal \.beamFrozenTime environment value to freeze the animation at specific timestamps for comparison.
    • Comparison: Every capture is diffed against a 'beam-off' render of the same card to ensure accuracy.

    Web Reference Capture: To capture a stable web frame for comparison, do not use negative animation-delay. Instead, pin the --beam-angle-<id> and --beam-opacity-<id> CSS properties directly via injected CSS.

    Execution Workflow:

    1. Run node scripts/parity-capture.mjs (requires dev server on :5173).
    2. Run ./snapshot.sh on the iOS side.
    3. Run python3 scripts/parity-diff.py to compare results.
    # 1. Capture web frames
node scripts/parity-capture.mjs

# 2. Run iOS snapshots
./snapshot.sh

# 3. Diff results
python3 scripts/parity-diff.py

  11. Run the border-beam-native example app

    main

    The example app showcases all 5 beam types with live pickers for color variants, themes, active states, and pulse tuning presets.

    Important: Because Skia and Reanimated are native modules, Expo Go will not work. You must use npx expo run:* to build a custom development client. The initial build includes a prebuild, CocoaPods installation, and compilation of React Native from source; expect this to take 15+ minutes.

    To run the app, use the following commands:

    1. Install dependencies:
      npm install
    2. Run on iOS:
      npx expo run:ios
    3. Run on Android:
      npx expo run:android
    npm install
npx expo run:ios
npx expo run:android

  12. Tune BorderBeam visual effects

    main

    Use the tuning prop to apply advanced visual adjustments. This allows you to access low-level controls equivalent to the web library's tuning parameters (like glow boost, stroke opacity, and core blur).

    You can use the WEB_DEMO_PULSE_PRESET to exactly match the visual style of the web demo, which is more intense than the default untuned beams.

    import { BorderBeam, WEB_DEMO_PULSE_PRESET } from 'border-beam-native';

<BorderBeam size="pulse-outside" tuning={WEB_DEMO_PULSE_PRESET}>…</BorderBeam>