Display Components

Display components render content — text, images, and other read-only visual elements. They work on all three surfaces.

Text

Renders a text string with typography variants.

Props

Prop	Type	Required	Description
content	string	Yes	Text content to display
variant	"heading" | "default" | "muted"	No	Typography preset (default: "default")
style	VisionStyle	No	Additional style (font size, color, etc.)

Variants

Variant	Description	Use case
"heading"	Bold, larger font size	Section titles, alert names
"default"	Normal body text	Primary content, scores, labels
"muted"	Dimmed, smaller font	Timestamps, secondary info, help text

Example

import { Text, VStack } from "@zaflun/lumio-sdk";

function ScoreDisplay({ homeScore, awayScore, teamA, teamB }) {
  return (
    <VStack gap={4}>
      <Text content={`${teamA} vs ${teamB}`} variant="heading" />
      <Text content={`${homeScore} - ${awayScore}`} variant="default" />
      <Text content="Live score" variant="muted" />
    </VStack>
  );
}

Custom styling

<Text
  content="Breaking news!"
  style={{
    color: "#ef4444",
    fontWeight: 700,
    fontSize: 20,
    letterSpacing: "0.05em",
    textTransform: "uppercase",
  }}
/>

---

Image

Renders an image with an accessible alt text.

Props

Prop	Type	Required	Description
src	string	Yes	Image URL (must be in the egress allowlist for external URLs)
alt	string	Yes	Accessible alt text
objectFit	"cover" | "contain" | "fill" | "none" | "scale-down"	No	How the image fills its container (default: "cover")
style	VisionStyle	No	Additional style (width, height, border-radius, etc.)

Example

import { Image, Box, Text, useLumioEvent } from "@zaflun/lumio-sdk";

function NowPlayingCard() {
  const event = useLumioEvent("spotify:track");

  if (!event) return null;

  const track = event.data;

  return (
    <Box style={{ display: "flex", gap: 12, alignItems: "center" }}>
      <Image
        src={track.albumArtUrl}
        alt={`Album art for ${track.album}`}
        objectFit="cover"
        style={{ width: 56, height: 56, borderRadius: 6, flexShrink: 0 }}
      />
      <Box>
        <Text content={track.title} variant="default" />
        <Text content={track.artist} variant="muted" />
      </Box>
    </Box>
  );
}

External images and egress

External image URLs must be in the egress allowlist in lumio.config.json:

{
  "egress": {
    "allowHosts": ["i.scdn.co", "*.spotifycdn.com"]
  }
}

Internal Lumio CDN images (profile avatars, uploaded assets) do not require egress allowlist entries.

---

IconDisplay

Renders any IconValue as the appropriate visual element.

Props

Prop	Type	Required	Description
icon	IconValue | null	Yes	The icon to render
size	number	No	Size in pixels (default: 24)
className	string	No	CSS class for styling

Rendering behavior

icon.type	Rendered as
lucide	Inline SVG (24x24 viewBox, stroke-based)
emoji	Text span with the Unicode character
emote	<img> with the CDN URL
upload	<img> with the upload URL
null	Empty placeholder

Example

import { IconDisplay } from "@zaflun/lumio-sdk";
import type { IconValue } from "@zaflun/lumio-sdk";

function AlertHeader({ icon }: { icon: IconValue | null }) {
  return (
    <HStack>
      <IconDisplay icon={icon} size={32} />
      <Text>Alert!</Text>
    </HStack>
  );
}

---

Display component guidelines

Principle	Guidance
Always provide alt text	Every Image needs a descriptive alt for accessibility
Use variant before custom style	Prefer variant="muted" over style={{ color: "#9ca3af" }} for consistency
Avoid fixed font sizes in the layer	Prefer relative units or theme-aware values to maintain readability at different canvas sizes
Keep text concise	Overlay text should be scannable at a glance — keep labels under 40 characters