Build your first widget

In this tutorial you'll build a small banner widget with configurable text, colour and size, then place it on an overlay. It takes a few minutes and you'll touch every part of the Widget Creator: the code editor, properties, the preview and the Build step.

By the end you'll have a widget that shows a message you can restyle without touching code.

1. Create the widget

1. Open Widget Creator from the sidebar.
2. Create a new widget and give it a name like My First Banner.

The editor opens with a starter widget and a live preview on the right.

2. Write the core

The core is the code that runs when your widget loads. Open the core file (a .ts file) and make it show your main template:

// main.ts
import { onLoad, showTemplate, setCrashTemplate, Template } from '@widget';

onLoad(() => {
  setCrashTemplate(Template.Crash); // a safe fallback if something throws
  showTemplate(Template.Main);      // draw the Main template
});

3. Draw something

Open the main.tsx template — this is a React component that draws your widget. Start with plain text:

// main.tsx
export default function Main() {
  return <h1>Hello, stream!</h1>;
}

The preview updates within a second. You've got a widget!

4. Make it configurable

Hard-coded text isn't much use. Let's add properties so anyone using the widget can set the message, colour and size without editing code.

Go to the Properties surface and add three properties:

Key	Type	Label	Default
message	text	Message	Hello, stream!
accent-colour	color	Colour	#9146FF
font-size	number	Font size	48

Now read them in the template with the useProp hook. A property's key becomes a camelCase name — accent-colour → accentColour, font-size → fontSize:

// main.tsx
import { useProp } from '@widget';

export default function Main() {
  const message = useProp('message');
  const colour = useProp('accentColour');
  const fontSize = useProp('fontSize');

  return (
    <div
      style={{
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        width: '100%',
        height: '100%',
        color: colour,
        fontSize: `${fontSize}px`,
        fontWeight: 800,
      }}
    >
      {message}
    </div>
  );
}

5. Try your controls

Switch to the Simulate surface and change your property test values — type a new message, pick a different colour, bump the size. The preview reacts immediately, exactly as it will for whoever configures the widget on their overlay.

tip

This is the form your viewers see when they add your widget. Good labels, sensible defaults and helpful descriptions make a widget pleasant to use — spend a moment on them.

6. Add a crash fallback

Open crash.tsx and make sure it returns something harmless. If your main template ever throws, this shows instead of a broken widget:

// crash.tsx
export default function Crash() {
  return null;
}

7. Build it and put it on an overlay

1. Click Build in the toolbar. This compiles your widget and makes it available on your own overlays.
2. Open an overlay in the Overlay Editor.
3. Click Add Widget, open the Custom widgets tab, and add My First Banner.
4. Position it, then tweak its message, colour and size in the properties panel — the same controls you defined.

That's a complete widget: code, configurable properties, live preview, and a real placement on an overlay. 🎉

Where to go next

• React to live events — make your widget respond to follows, subs and more.
• Property schema — every field type and option.
• The @widget runtime — the full API, including ready-made Text, Image and ProgressBar components.