Velaguides

Vide

Use Vela with Vide. No config needed, the same static output, and a function for any class that changes.

Vela works with Vide as well as React. Everything else in these docs, from utilities and variants to the theme, applies to both.

You don’t need any Vela config for Vide. Vela detects it from the jsxFactory your tsconfig.json already sets:

tsconfig.json
{
"compilerOptions": {
"jsx": "react",
"jsxFactory": "Vide.jsx",
"jsxFragmentFactory": "Vide.Fragment"
}
}

Follow Installation, installing @rbxts/vide instead of React. The Vide runtime ships with vela-rbxts. To set the target by hand instead, see naming the target explicitly.

The static path is almost the same output

Classes Vela resolves at compile time produce the same props under both targets. Vide uses the same lowercase Roblox element names as React, and its props are Roblox properties.

The one difference is how rem-scaled offsets are written:

React: one scaled prop each
<frame BackgroundColor3={Color3.fromRGB(49, 65, 88)} Size={__VelaRem.scale(UDim2.fromOffset(160, 0), 4)}>
<uipadding PaddingTop={__VelaRem.scale(new UDim(0, 16), 0)} />
</frame>
Vide: one binding child per instance
<frame BackgroundColor3={Color3.fromRGB(49, 65, 88)}>
<uipadding>{__VelaRem.bind({ PaddingTop: new UDim(0, 16) })}</uipadding>
{__VelaRem.bind({ Size: UDim2.fromOffset(160, 0) })}
</frame>

The binding is a Vide action, so it works inside a function child. If a spread follows the className, each prop keeps its own binding so the spread can override it.

Lowered files import from @rbxts/vela-runtime-vide instead of @rbxts/vela-runtime. With rem pinned, as in the previews on this site, nothing is scaled and the two outputs match line for line.

A dynamic class value has to be a thunk

This is the one thing you write differently. A Vide component body runs once, so a class that changes must be a function, like any other derived Vide prop:

src/client/Button.tsx
const active = source(false);
// Tracked: re-read whenever `active` changes.
<textbutton className={() => (active() ? "bg-blue-600" : "bg-slate-700")} />
// Not tracked: read once, when the component body ran.
<textbutton className={active() ? "bg-blue-600" : "bg-slate-700"} />

The editor works inside the function. Completions, hover, swatches, diagnostics and sorting behave as they do on a plain string.

A thunk changes tracking, not compilation. Vela still sees both class strings in the source and resolves them at compile time, as it does for React. Only the active() test is wrapped. Both targets produce the same two __velaRules. Only the line inside __velaTests and the runtime import differ:

src/client/Button.tsx
import Vide, { source } from "@rbxts/vide";
export function Button() {
const active = source(false);
return (
<textbutton
className={() => (active() ? "bg-blue-600" : "bg-slate-700")}
Text="Ready"
/>
);
}
Emitted for Vide
import { createVelaRuntimeHost } from "@rbxts/vela-runtime-vide";
import type { VelaRuntimeHostComponent } from "@rbxts/vela-runtime-vide";
const VelaRuntimeHost = createVelaRuntimeHost({
"preflight": true,
"theme": {
"colors": {},
"radius": {},
"spacing": {},
"fontFamily": {},
"screens": {},
"rem": {
"base": 16.0,
"min": 8.0,
"max": 64.0,
"baseResolution": {
"x": 1920.0,
"y": 1020.0
}
},
"replaced": [
"colors",
"radius",
"spacing",
"fontFamily",
"screens"
]
},
"plugins": {
"utilities": {}
}
}) as unknown as VelaRuntimeHostComponent;
import Vide, { source } from "@rbxts/vide";
export function Button() {
const active = source(false);
return (<VelaRuntimeHost Text="Ready" BorderSizePixel={(0 as never)} BackgroundTransparency={(1 as never)} __velaRules={[
{
"condition": {
"kind": "test",
"index": 0,
"expected": true
},
"effects": {
"props": [
{
"name": "BackgroundColor3",
"value": "Color3.fromRGB(21, 93, 252)"
},
{
"name": "BackgroundTransparency",
"value": "0"
}
],
"helpers": []
}
},
{
"condition": {
"kind": "test",
"index": 0,
"expected": false
},
"effects": {
"props": [
{
"name": "BackgroundColor3",
"value": "Color3.fromRGB(49, 65, 88)"
},
{
"name": "BackgroundTransparency",
"value": "0"
}
],
"helpers": []
}
}
]} __velaTests={[
()=>active() ? true : false
]} __velaTag={"textbutton"}/>);
}
The same button under both targets, lowered by the compiler at build time. Switch the tab: the rules do not move.

What the runtime host does differently

On a host element, nothing you need to handle. The Vide host keeps each property in sync with the current classes. A property that drops out goes back to what the element declared, or to the Roblox default.

Interaction variants, transition-*, animate-*, text transforms, divide-* and opacity-* all behave as they do under React. So do touch:, gamepad: and dark:. They update when a gamepad is plugged in, when the VelaColorScheme attribute changes, or when LocalPlayer arrives late.

Two limits come from how Vide works, and both affect components.

A component element’s props are fixed at the call

Vide passes props to a component once, when it’s called. So the set of props Vela can pass down is fixed at that moment:

Both branches are known when Card is called
<Card className={() => (loud() ? "bg-red-500 rounded-xl" : "bg-slate-700")} />

This works, because Vela reads both branches up front and passes both BackgroundColor3 and the UICorner. A prop that no branch names at call time can’t be added later. Host elements don’t have this limit.

A late m-* cannot be honoured

A margin is a wrapper instance around the element. Vide parents an element as soon as it’s built, so the wrapper can’t be added afterwards.

When a class value names m-* anywhere Vela can see it, Vela emits __velaMarginBox and the host builds the wrapper first:

src/client/Panel.tsx
import Vide from "@rbxts/vide";
export function Panel(p: { big: () => boolean }) {
return <frame className={() => (p.big() ? "m-4 p-2" : "p-2")} />;
}
Emitted for Vide
import { createVelaRuntimeHost } from "@rbxts/vela-runtime-vide";
import type { VelaRuntimeHostComponent } from "@rbxts/vela-runtime-vide";
const VelaRuntimeHost = createVelaRuntimeHost({
"preflight": true,
"theme": {
"colors": {},
"radius": {},
"spacing": {},
"fontFamily": {},
"screens": {},
"rem": {
"base": 16.0,
"min": 8.0,
"max": 64.0,
"baseResolution": {
"x": 1920.0,
"y": 1020.0
}
}
},
"plugins": {
"utilities": {}
}
}) as unknown as VelaRuntimeHostComponent;
import Vide from "@rbxts/vide";
export function Panel(p: {
big: () => boolean;
}) {
return <VelaRuntimeHost className={()=>p.big() ? "m-4 p-2" : "p-2"} BorderSizePixel={(0 as never)} BackgroundTransparency={(1 as never)} __velaMarginBox={true} __velaTag={"frame"}/>;
}
React gets no such prop — the same component, written the way each target writes it.

React doesn’t need this, because it renders the wrapper and the margin together.

If a margin arrives from a value Vela can’t see into, such as a function call, the runtime warns instead of rendering without the margin.

Naming the target explicitly

Set framework in vela.config.ts to choose the target yourself:

vela.config.ts
import { defineConfig } from "vela-rbxts";
export default defineConfig({ framework: "vide" });

Writing the key at all turns detection off. framework: "react" forces React even with a Vide jsxFactory. Most Vide projects don’t need either.

You need framework: "vide" only when detection can’t find your factory. Detection walks up from each source file to the nearest tsconfig.json. It follows a relative extends up to eight levels and reads compilerOptions.jsxFactory. A factory starting with Vide. selects Vide. Anything else, or nothing found, means React. A non-relative extends, or one nested deeper than eight levels, is missed.

Writing the declaration file

Same as React. One import adds className to both React.Attributes and Vide.Attributes:

src/vela-env.d.ts
import "vela-rbxts";

See also