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:
{ "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:
<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><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:
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"} />className accepts both forms, so the second line type-checks. It just never updates, and nothing warns you.
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:
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" /> );}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"}/>);}import React, { useState } from "@rbxts/react";
export function Button() { const [active] = useState(false);
return ( <textbutton className={active ? "bg-blue-600" : "bg-slate-700"} Text="Ready" /> );}import { createVelaRuntimeHost } from "@rbxts/vela-runtime";import type { VelaRuntimeHostComponent } from "@rbxts/vela-runtime";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 React, { useState } from "@rbxts/react";export function Button() { const [active] = useState(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"}/>);}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:
<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:
import Vide from "@rbxts/vide";
export function Panel(p: { big: () => boolean }) { return <frame className={() => (p.big() ? "m-4 p-2" : "p-2")} />;}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"}/>;}import React from "@rbxts/react";
export function Panel(props: { big: boolean }) { return <frame className={props.big ? "m-4 p-2" : "p-2"} />;}import { createVelaRuntimeHost } from "@rbxts/vela-runtime";import type { VelaRuntimeHostComponent } from "@rbxts/vela-runtime";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 React from "@rbxts/react";export function Panel(props: { big: boolean;}) { return <VelaRuntimeHost className={props.big ? "m-4 p-2" : "p-2"} BorderSizePixel={(0 as never)} BackgroundTransparency={(1 as never)} __velaTag={"frame"}/>;}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:
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.
jsxFactory applies to the whole program, so a project can’t mix React and Vide files.
Writing the declaration file
Same as React. One import adds className to both React.Attributes and Vide.Attributes:
import "vela-rbxts";See also
- Dynamic class names: what a branch costs, on both targets.
framework: the config key.- Release notes: what shipped with Vide support.