Box

The Box component is a themed container that provides a background, border, rounded corners, padding, and shadow. It is useful for grouping related UI elements such as forms, cards, panels, or settings sections.

Example

Sizing

Box supports the standard sizing props, allowing it to fill available space or use fixed dimensions.

<Box width="300px" height="200px">
    <Text text="Fixed size box" />
</Box>

Background image

Theme authors can set theme.components.box.backgroundImage to layer a 9-slice or scaled image on top of every Box's background colour. This is purely additive — backgroundColor, border-color, corner radius, and box-shadow all keep working unchanged, so it's a way to build custom visual skins (a wooden-frame box, a beveled button, etc.) without giving up the existing token-based options. The border stroke still draws on top of the image, the corner radius still clips it, and the shadow still applies outside it.

Box also accepts a background-image prop directly, which overrides the themed backgroundImage for that single instance — the same pattern used by border-color/border-thickness.

Unlike CSS's border-image-slice, slice isn't an edge inset — it's the two literal corner points of the unscaled centre region, in absolute source-image pixel coordinates (the same values you'd pass to Roblox's own SliceCenter/Rect.new(minX, minY, maxX, maxY)). Roblox has no API for deriving those coordinates from an inset alone, so picking sensible values means knowing the source image's actual pixel dimensions. The example below assumes a 128x128 source image with a 12px sharp border, so the unscaled centre region runs from (12, 12) to (116, 116):

<Box
    spacing="md"
    background-image={{
        image: "rbxassetid://1234567890",
        slice: "12 116",
    }}
>
    <Text text="Wooden Frame" variant="heading" />
</Box>

slice's coordinates are always the border's literal pixel size in the source image, so that same 12px border would otherwise render at 12px on every Box regardless of size. Add sliceScale (below 1) to shrink the rendered border thickness without touching slice itself:

<Box
    spacing="md"
    background-image={{
        image: "rbxassetid://1234567890",
        slice: "12 116",
        sliceScale: 0.5,
    }}
>
    <Text text="Thinner border" variant="heading" />
</Box>

Use createTheme (or extendTheme) to set components.box.backgroundImage theme-wide instead, then apply it to a subtree with ThemeProvider:

import { Box, createTheme, ThemeProvider, VStack, Text } from "@rbxts/react-clean-ui";

const themeWithBackgroundImage = createTheme({
    components: {
        box: {
            backgroundImage: {
                image: "rbxassetid://1234567890",
                slice: "12 116",
            },
        },
    },
});

<ThemeProvider theme={themeWithBackgroundImage}>
    <Box spacing="md">
        <VStack>
            <Text text="Wooden Frame" variant="heading" />
            <Text text="The border, corner radius, and shadow still render on top of the image." />
        </VStack>
    </Box>
</ThemeProvider>

backgroundImage accepts a CssBackgroundImage object:

To tile an image instead of stretching it, pair size: Enum.ScaleType.Tile with a tileSize (e.g. "25% 25%" to repeat it 4x4 across the box):

<Box
    spacing="md"
    background-image={{
        image: "rbxassetid://1234567890",
        size: Enum.ScaleType.Tile,
        tileSize: "25% 25%",
    }}
>
    <Text text="Tiled pattern" variant="heading" />
</Box>

Background gradient

Theme authors can set theme.components.box.backgroundGradient to layer a UIGradient on top of every Box's background colour. Like backgroundImage, this is purely additive — backgroundColor, border-color, corner radius, and box-shadow all keep working unchanged, and the gradient renders underneath the border stroke and inside the clipped corner radius.

Box also accepts a background-gradient prop directly, which overrides the themed backgroundGradient for that single instance — the same pattern used by background-image.

<Box
    spacing="md"
    background-gradient={{
        colors: [Color3.fromHex("#4F46E5"), Color3.fromHex("#EC4899")],
        rotation: 45,
    }}
>
    <Text text="Gradient Box" variant="heading" />
</Box>

Use createTheme (or extendTheme) to set components.box.backgroundGradient theme-wide instead, then apply it to a subtree with ThemeProvider:

import { Box, createTheme, ThemeProvider, VStack, Text } from "@rbxts/react-clean-ui";

const themeWithBackgroundGradient = createTheme({
    components: {
        box: {
            backgroundGradient: {
                colors: [Color3.fromHex("#4F46E5"), Color3.fromHex("#EC4899")],
                rotation: 45,
            },
        },
    },
});

<ThemeProvider theme={themeWithBackgroundGradient}>
    <Box spacing="md">
        <VStack>
            <Text text="Gradient Box" variant="heading" />
            <Text text="The border, corner radius, and shadow still render on top of the gradient." />
        </VStack>
    </Box>
</ThemeProvider>

backgroundGradient accepts a CssBackgroundGradient object:

Props

Notes

• Uses the current theme for colours, border, corner radius, shadow, padding, and (optionally) background image.
• Automatically sizes vertically to fit its children.
• Accepts any child components.