Bloxwind

Bloxwind supplies Tailwind-style utility classes for Roblox React. At run time, it converts each className string into Roblox properties and UI modifier children.

Bloxwind works with Luau and Rojo. It does not require a source transform.

Read the API reference for all public types, fields, utilities, and behavior.

local Bloxwind = require(ReplicatedStorage.Packages.Bloxwind)
local tw = Bloxwind.create(require(ReplicatedStorage.Shared.BloxwindConfig))

return React.createElement(tw.Frame, {
    className = "w-full h-auto bg-slate-900 rounded-xl p-4 flex-row items-center gap-2",
})

Install

1. Add Bloxwind and the matching React packages to wally.toml.

[dependencies]
Bloxwind = "jerren/bloxwind@0.1.0"
React = "roblox/react@17.3.11"
ReactRoblox = "roblox/react-roblox@17.3.11"

2. Run wally install.
3. Map the Packages directory into ReplicatedStorage.
4. Require Bloxwind.
5. Create one configured Bloxwind instance for the application.

Configuration

A configuration ModuleScript defines the theme and the custom utilities. It can replace a complete theme scale or extend individual tokens.

return {
    diagnostics = "warn", -- "warn", "strict", or "silent"
    theme = {
        extend = {
            colors = {
                brand = {
                    [500] = Color3.fromHex("466EFF"),
                    [600] = Color3.fromHex("3255DC"),
                },
            },
            spacing = {
                ["18"] = 72,
            },
        },
    },
    utilities = {
        card = function(theme)
            return {
                properties = {
                    BackgroundColor3 = theme.colors.slate["900"],
                },
                decorators = {
                    outline = {
                        className = "UIStroke",
                        properties = {
                            Color = theme.colors.slate["700"],
                            Thickness = 1,
                        },
                    },
                },
            }
        end,
    },
}

Use theme.colors = {...} to replace the bundled color scale. Use theme.extend.colors = {...} to add or replace individual color tokens.

Bloxwind checks custom utilities before it checks built-in utilities. Thus, a custom utility can replace a built-in utility that has the same name.

Variant prefixes also accept custom utilities. For example, hover:card applies the custom card utility during the hover state.

A decorator slot name identifies a modifier. Bloxwind assigns one standard slot to each modifier class. This action prevents duplicate modifier instances.

Bloxwind supports these custom modifiers:

• UIPadding
• UIListLayout
• UICorner
• UIStroke
• UISizeConstraint
• UIAspectRatioConstraint
• UIFlexItem
• UIGradient

By default, Bloxwind reports each invalid utility once and ignores it. Set diagnostics = "strict" to stop immediately after an error.

Set diagnostics = "silent" to ignore invalid utilities without a report.

Components and states

A configured Bloxwind instance contains these components:

• Frame
• ScrollingFrame
• CanvasGroup
• TextLabel
• TextButton
• TextBox
• ImageLabel
• ImageButton
• ViewportFrame
• VideoFrame

Use tw.styled("Frame", "rounded-lg p-4") to create a component with a fixed set of base utilities.

Bloxwind supports the hover:, pressed:, and disabled: state variants. It applies active utilities from left to right.

The disabled wrapper property makes a button non-interactable.

React.createElement(tw.TextButton, {
    className = "bg-blue-500 hover:bg-blue-600 pressed:bg-blue-700 disabled:bg-slate-800",
    disabled = isUnavailable,
    Text = "Continue",
})

Bloxwind runs its interaction listener before it runs the listener from the user. Explicit Roblox properties override utility properties because Bloxwind assigns them last.

Utility reference

• Sizing utilities include w-*, h-*, w-full, w-1/2, w-auto, min-w-*, max-h-*, aspect-square, and aspect-video.
• Spacing utilities include p-*, px-*, py-*, directional padding, gap-*, gap-x-*, and gap-y-*.
• Layout utilities include flex, flex-row, flex-col, flex-wrap, justify-*, items-*, grow, shrink, and flex-1.
• Color utilities include bg-*, text-*, image-*, border-*, and channel opacity utilities.
• Typography utilities control text size, font family, font weight, alignment, wrapping, and truncation.
• Appearance utilities control corners, borders, visibility, clipping, z-index, and CanvasGroup opacity.

The default spacing scale uses four-pixel increments. Each bundled color family contains shades 50 through 950.

Roblox differences

Bloxwind does not emulate CSS. It maps utilities to Roblox types such as UDim2, UIListLayout, UIPadding, UICorner, and UIStroke.

The Roblox UI model does not have a browser box model. Bloxwind does not create wrapper instances to simulate margins.

Use opacity-* only with CanvasGroup. For other instances, use bg-opacity-*, text-opacity-*, or image-opacity-*.

Version 0.1 does not include arbitrary bracket values, responsive variants, dark variants, animations, parser plugins, or a native StyleSheet backend.

Add a theme token or a named custom utility when a built-in utility is not sufficient.

Develop and test

1. Install the dependencies.

wally install

2. Build the demonstration place.

rojo build -o bloxwind.rbxlx

3. Build the test place.

rojo build test.project.json -o bloxwind-tests.rbxlx

4. Open bloxwind-tests.rbxlx in Roblox Studio.
5. Run the test place.

TestEZ runs the test suite when the test place starts. The default project shows a Bloxwind demonstration.

Contributors

See CONTRIBUTORS.md for project credits.