Components

The Vision SDK provides 13 components organized into three categories. Import them from @1upvision/sdk.

Layout

Box, CompactView, List, VStack, HStack

Display

Text, Image

Inputs

Button, Toggle, TextField, Dropdown, and more

Custom Styling

All components accept an optional style prop of type VisionStyle. This is a typed subset of CSS properties that gets sanitized by the host before rendering as inline styles.

import type { VisionStyle } from "@1upvision/sdk";

Fonts

The SDK supports two font-loading paths for extensions:

Google Fonts via vision.config.json

{
  "fonts": ["Inter", "Space Mono"]
}

Local fonts via localFont()

import { Text, localFont } from "@1upvision/sdk";

const headingFont = localFont({
  src: "/fonts/Orbitron-Bold.woff2",
  family: "Orbitron",
  fallback: ["sans-serif"],
});

<Text content="SCORE" style={{ ...headingFont.style, fontSize: 36 }} />;

Local font files should live in your extension project’s public/ directory. They are copied into dist/ automatically by the CLI.

Supported Properties

Category	Properties
Layout	`display`, `flexDirection`, `flexWrap`, `alignItems`, `justifyContent`, `alignSelf`, `gap`, `flex`, `flexGrow`, `flexShrink`, `flexBasis`, `gridTemplateColumns`, `gridTemplateRows`, `gridColumn`, `gridRow`, `gridGap`
Position	`position` (`"relative"` or `"absolute"` only), `top`, `right`, `bottom`, `left`, `zIndex`
Sizing	`width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `aspectRatio`
Spacing	`padding`, `paddingTop/Right/Bottom/Left`, `margin`, `marginTop/Right/Bottom/Left`
Colors	`color`, `backgroundColor`, `background`, `opacity`
Border	`border`, `borderWidth`, `borderColor`, `borderStyle`, `borderRadius`, `borderTop/Right/Bottom/Left`
Typography	`fontSize`, `fontWeight`, `fontFamily`, `fontStyle`, `textAlign`, `textDecoration`, `textTransform`, `lineHeight`, `letterSpacing`, `whiteSpace`, `overflow`, `textOverflow`, `wordBreak`
Transform & Animation	`transform`, `transformOrigin`, `transition`, `animation`, `animationName`, `animationDuration`, `animationTimingFunction`, `animationDelay`, `animationIterationCount`, `animationDirection`, `animationFillMode`, `animationPlayState`
Effects	`boxShadow`, `textShadow`, `filter`, `backdropFilter`
Other	`objectFit`, `pointerEvents`, `userSelect`, `cursor`, `overflowX`, `overflowY`

Security Restrictions

For security, the following are blocked by the host sanitizer:

position: "fixed" and position: "sticky" — only "relative" and "absolute" are allowed
url() values in component styles — use localFont() for fonts and <Image> for images
expression(), javascript:, @import, and other injection vectors

Keyframe Animations

Use defineKeyframes to create CSS @keyframes animations. Define keyframes at module scope and reference them in animation or animationName style properties.

import { Box, Text, defineKeyframes } from "@1upvision/sdk";

const fadeIn = defineKeyframes({
  from: { opacity: 0 },
  to: { opacity: 1 },
});

const pulse = defineKeyframes({
  "0%": { transform: "scale(1)" },
  "50%": { transform: "scale(1.05)" },
  "100%": { transform: "scale(1)" },
});

function AnimatedOverlay() {
  return (
    <Box style={{ animation: `${fadeIn} 0.3s ease-out` }}>
      <Text
        content="LIVE"
        style={{
          animationName: pulse,
          animationDuration: "2s",
          animationIterationCount: "infinite",
          color: "#ff4444",
          fontWeight: "bold",
        }}
      />
    </Box>
  );
}

Keyframe stop labels can be from, to, or percentage values like 0%, 50%, 100%. Each stop accepts the same VisionStyle properties. The host sanitizes all keyframe values using the same security rules as inline styles.

Overlay Example

Build a custom scoreboard overlay using Box and styled components:

import { Box, Text, useExtensionStorage } from "@1upvision/sdk";

function ScoreOverlay() {
  const [storage] = useExtensionStorage();

  return (
    <Box
      style={{
        display: "flex",
        alignItems: "center",
        gap: 24,
        padding: "12px 24px",
        background: "rgba(0, 0, 0, 0.8)",
        borderRadius: 8,
        color: "#fff",
      }}
    >
      <Text content="HOME" style={{ fontSize: 14, opacity: 0.7 }} />
      <Text
        content={String(storage.homeScore ?? 0)}
        style={{ fontSize: 32, fontWeight: "bold" }}
      />
      <Text content="—" style={{ fontSize: 24, opacity: 0.5 }} />
      <Text
        content={String(storage.awayScore ?? 0)}
        style={{ fontSize: 32, fontWeight: "bold" }}
      />
      <Text content="AWAY" style={{ fontSize: 14, opacity: 0.7 }} />
    </Box>
  );
}

Behavior by Target

Components behave differently depending on where they render:

Component	Editor	Interactive	OBS Layer
CompactView	Container	Container	Container
List	Container	Container	Container
Box	Container	Container	Container
VStack	Container	Container	Container
HStack	Container	Container	Container
Text	Text	Text	Text
Image	Image	Image	Image
Button	Interactive	Interactive	Hidden
TextField	Editable	Editable	Shows value as text
TextArea	Editable	Editable	Shows value as text
NumberField	Editable	Editable	Shows value as text
Toggle	Interactive	Interactive	Shows “On” / “Off”
Dropdown	Interactive	Interactive	Shows selected label

Input components are fully interactive in the editor and interactive page. On the OBS layer, they degrade to static display since viewers can’t interact with the overlay.

Custom Widgets

Extensions SDK

Layout

Display

Inputs

Custom Styling

Fonts

Supported Properties

Security Restrictions

Keyframe Animations

Overlay Example

Behavior by Target

Layout

Display

Inputs

​Custom Styling

​Fonts

​Supported Properties

​Security Restrictions

​Keyframe Animations

​Overlay Example

​Behavior by Target

Custom Styling

Fonts

Supported Properties

Security Restrictions

Keyframe Animations

Overlay Example

Behavior by Target