This page answers “does AutomaticCanvasSize work?” for each instance and property. For the
area-level picture, see Scope and status.
How to read this
| Mark | Meaning |
|---|---|
| Supported | Read by the layout engine or painted by the renderer. Behaves like Roblox, within the limits noted. |
| Partial | Implemented with a stated gap. Right in the common case, wrong at the edge. |
| Accepted | Typed and settable, but nothing reads it. No error, no effect. |
| Not typed | No JSX prop and no runtime handling. A compile error, and it wouldn’t render either. |
Accepted is the mark that costs you time: the prop compiles and does nothing. These props exist so component code written for Roblox runs in the preview without edits.
Enum props take a bare string anywhere they take the item: AutomaticSize="XY" is
Enum.AutomaticSize.XY. EnumItem.Value is the engine’s own number for the item.
Instances
| Intrinsic | Status | Notes |
|---|---|---|
screengui surfacegui billboardgui | Supported | LayerCollectors: never background-painted, always click-through, ordered among themselves by DisplayOrder. |
frame | Supported | |
scrollingframe | Supported | Sinks pointer input unconditionally, like Roblox. |
canvasgroup | Supported | GroupTransparency becomes CSS opacity on the container, which fades the composited subtree as Roblox does. |
textlabel textbutton textbox | Supported | See Text properties. |
imagelabel imagebutton | Supported | The Image paints in a layer beneath the text, in every ScaleType. See Image properties. |
viewportframe videoframe | Partial | Typed and laid out as plain GuiObjects. No 3D scene and no video; they paint as backgrounds. |
uilistlayout uigridlayout uipadding | Supported | |
uipagelayout uitablelayout | Supported | See Layout and modifier properties. |
uicorner uistroke uigradient | Supported | A per-corner border-radius, a box-shadow ring on the side BorderStrokePosition asks for, and a CSS linear-gradient. |
uishadow | Partial | A CSS drop shadow under any UIStroke ring. Only the first UIShadow child is read. The beta Inset and Mode properties are not typed, so an inset or text shadow paints as a drop shadow or not at all. |
uisizeconstraint uiaspectratioconstraint | Supported | |
uiscale | Supported | Multiplies the size the parent resolves, and everything under it, by Scale. |
uiflexitem | Supported | FlexMode: Grow, Shrink, Fill, or Custom with GrowRatio / ShrinkRatio. See flex. |
| Everything else | Not typed | uitextsizeconstraint, folder, part, … The intrinsic set is exactly what the renderer implements. |
GuiObject properties
Shared by every visual class.
| Property | Status | Notes |
|---|---|---|
Size Position AnchorPoint | Supported | Full UDim2 scale and offset. |
AutomaticSize | Supported | X / Y / XY grow to content. Size is the floor and the width the parent leaves is the ceiling. See below. |
BackgroundColor3 BackgroundTransparency | Supported | |
Visible | Supported | Hidden with CSS. The node still takes up its rect, as in Roblox. |
ZIndex | Supported | ZIndexBehavior.Sibling semantics. A node’s own image, text and TextBox input always paint beneath its children, whatever its ZIndex. |
LayoutOrder | Supported | Honored by every layout under SortOrder.LayoutOrder, which is not the default. See SortOrder defaults to Name. |
Rotation | Supported | Degrees clockwise about the center, as a CSS transform. Visual only: the layout rect is unrotated, as in Roblox. |
ClipsDescendants | Supported | |
Active | Partial | Works at runtime but isn’t in the props type, so your editor will flag it. It decides whether input is sunk, not whether the object hears it. See Input. |
Name | Supported | Set from the element’s key, or the nearest keyed ancestor’s, as React-Lua does. <frame key="Content"> is found by FindFirstChild("Content"). |
| (unwritten properties) | Supported | Reading a property nobody wrote returns the Roblox default (Visible, ZIndex, BackgroundTransparency, Rotation, LayoutOrder, Active, ClipsDescendants, AnchorPoint, Position, Size), not undefined. |
Event Change ref | Supported | Event={{ Activated }}, Change={{ Text }}, and ref to the live LoomInstance. |
BorderSizePixel BorderColor3 BorderMode | Partial | Painted at runtime but not in the props type. A ring outside the rect (Outline), inside it (Inset) or straddling it (Middle). The engine’s 1px dark default is drawn too, faded by BackgroundTransparency, so an invisible container has no border. |
SizeConstraint Transparency Interactable | Not typed |
ScreenGui properties
| Property | Status | Notes |
|---|---|---|
DisplayOrder | Supported | Becomes the layer’s CSS z-index, negative values included. |
Enabled | Supported | |
ZIndexBehavior | Accepted | Sibling is what the renderer already does. Global is not emulated. |
IgnoreGuiInset | Accepted | GetGuiInset() is zero, so there is no inset to ignore. |
ResetOnSpawn ScreenInsets | Accepted | Nothing reads them. |
Text properties
| Property | Status | Notes |
|---|---|---|
Text TextColor3 TextSize TextTransparency | Supported | A newline breaks the line and a run of spaces stays a run of spaces, as in Roblox. |
TextXAlignment TextYAlignment | Supported | |
TextWrapped | Supported | white-space: normal or nowrap, and applied during measurement. See below. The deprecated TextWrap alias reads as the same property and is in the props type. |
LineHeight | Supported | Clamped to Studio’s 1–3 and spent between lines: n lines measure TextSize + (n - 1) * TextSize * LineHeight, so a one-line label is exactly TextSize tall. See below. |
FontFace | Supported | new Font(family, weight, style) resolved to a CSS family, weight and slant, for painting and measuring. Wins over the legacy Font enum when both are set. |
Font | Supported | The legacy enum, all 53 items in the engine’s order, mapped to a family by name prefix and a weight by name suffix. 28 families load a real face. The eight the engine licenses privately (Gotham, BuilderSans, Bodoni, …) resolve to a fallback stack and warn. See Fonts and text metrics. |
FontSize | Supported | The legacy Enum.FontSize. The pixel size is read from the name, so Size24 paints and measures at 24px. TextSize wins when both are set, as in Roblox. |
RichText | Supported | <b>, <i>, <u>, <s>, <br/>, <font> (color, size, face, family, weight, transparency), <uppercase> / <smallcaps> and the character entities. With the flag off, or on a tag the engine wouldn’t recognize, the markup stays literal, as in Roblox. Each run is measured in its own font. |
TextScaled | Supported | The largest whole size from 1 to 100 at which the string fits the box, always wrapping. TextSize is not read. |
TextTruncate MaxVisibleGraphemes TextStrokeColor3 TextStrokeTransparency | Not typed | No ellipsis, no glyph outline. |
AutomaticSize on text
Text is measured in the browser with a canvas measureText(), in the font the renderer paints. The
result becomes TextBounds. Which typeface that is, and why to pin it, is covered in
Fonts and text metrics.
TextWrappedwraps at word boundaries. One function decides every wrap, for both measuring and painting.- The wrap width is the nearest ancestor with a width of its own, not the immediate parent, minus every
UIPaddingin between. A parent that is itselfAutomaticSizeis sized by the label, so it never causes a wrap. - Scale
UIPaddinginsets count too. They resolve against the node’s width on a real axis, and against zero on an automatic axis. - A
RichTextstring is measured run by run in each run’s font, so bold text doesn’t clip. - An empty
TextBoxis measured against itsPlaceholderText, so anAutomaticSize.Yinput doesn’t collapse to zero height. - When a container narrows, the adapter re-runs layout until the measurement and the width agree, up to four passes before deferring to the next frame. It patches the DOM once.
The React and vide adapters both do this, so a scene lays out the same through either.
TextSize is a face height, not a font size
Roblox fits the whole face, ascender to descender, into TextSize. CSS font-size sets the em
square, and most faces run well past it. Loom scales by a per-family ratio so glyphs come out the
size Roblox draws them. See
TextSize is not a font size.
LineHeight sets the line box in pixels from TextSize. The clip rect makes room for the browser’s
taller line boxes, so a paragraph’s last line keeps its descenders. Layout doesn’t move, and a label
still clips its text at its left and right edges.
AutomaticSize is bounded by the parent
An AutomaticSize object grows up to the width its parent leaves, as in Roblox. A TextWrapped
label grows to that width, then wraps.
- The ceiling is inherited through any padding in between. A wrapping
UIListLayoutwraps against the same ceiling. Sizestays the floor, even past the ceiling.- Content that still doesn’t fit overflows, as it does in the engine.
- Height is not capped. An auto-height panel inside a
ClipsDescendantsframe can tween open to its fullAbsoluteSize.Y. - A child counts at its full size wherever its
AnchorPointputs it. A 14×14 icon anchored at its center still sizes its parent to 14×14. - In a
ScrollingFrame, children get no ceiling on an axis withAutomaticCanvasSizeor aCanvasSizeof 0. ACanvasSizewith a real extent is still a ceiling.
Image properties
Shared by imagelabel and imagebutton. The image paints as a background layer beneath the text,
not as an <img>.
| Property | Status | Notes |
|---|---|---|
Image | Supported | http(s):, data: and blob: URLs load directly. rbxassetid:// is resolved for you; see below. |
ImageTransparency | Supported | |
ImageColor3 | Supported | A per-channel multiply through an feColorMatrix, as in the engine, so a full-color image tints correctly. The default white adds no filter. |
ScaleType | Supported | All five: Stretch, Fit, Crop, Slice, Tile. |
SliceCenter SliceScale | Supported | The 9-slice center in source pixels, painted as a CSS border-image: corners keep their size, edges stretch on one axis, the middle on both. SliceScale scales the painted border. A SliceCenter that leaves no center, including the default Rect.new(0, 0, 0, 0), stretches instead. |
TileSize | Supported | One tile’s size for ScaleType.Tile, as a UDim2 against the node. UDim2.fromScale(0.5, 0.5) is four tiles. Defaults to one tile filling the node. |
ImageRectOffset ImageRectSize | Supported | The sprite window, in image pixels. A zero ImageRectSize means the whole image, as in Roblox. The window is clipped to its destination, so neighboring sprites never leak under Fit. |
ResampleMode | Supported | Pixelated becomes CSS image-rendering: pixelated, so pixel art scales up crisp. |
Two combinations are not reproduced:
ScaleType.Tilewith anImageRectwindow. CSS can’t repeat a region, so the whole image tiles and loom warns once, naming the node.- A
SliceCentermeasured against a window. Slice insets are read against the whole source image.
rbxassetid:// resolution
| Where | How |
|---|---|
Dev server (loom preview, the embedded server, Next dev) | Resolved server-side and answered as a redirect from <base>__loom/asset/<id>. Lookups are batched, up to 100 IDs per thumbnail request with at most two in flight, and a throttled request is retried after its Retry-After. |
Static build (loom build, vite build) | Resolved at build time and downloaded into the output, with a __loom/assets.json manifest. The build reads IDs from the emitted code and from a first render of each gallery target. See Static builds and embedding. |
A static build misses an ID that only appears after interaction. Install your own resolver with setImageResolver for those.
TextBox properties
| Property | Status | Notes |
|---|---|---|
PlaceholderText | Supported | Becomes the input’s placeholder. |
ClearTextOnFocus TextEditable MultiLine | Supported | |
PlaceholderColor3 | Accepted | You get the browser’s default placeholder color. |
ScrollingFrame properties
| Property | Status | Notes |
|---|---|---|
CanvasSize | Supported | Children lay out against the canvas, not the window. |
CanvasPosition | Supported | Applied as the DOM scroll offset. |
AutomaticCanvasSize | Supported | X / Y / XY. The axis grows to the bounding box of the frame’s direct children, then takes the larger of that and CanvasSize. |
ScrollingDirection ScrollingEnabled | Supported | Decide which axes scroll, and so which bars can appear. |
ScrollBarThickness | Supported | Bar width, default 12. 0 shows no bar, as in Roblox. |
ScrollBarImageColor3 | Supported | Tints the thumb. Untinted, loom draws the engine’s grey, not the property’s white default, which would be invisible on most surfaces. |
ScrollBarImageTransparency | Accepted | The thumb is opaque. |
VerticalScrollBarInset HorizontalScrollBarInset | Accepted | The bar always paints over the canvas (ScrollBarInset.None, the engine default). AbsoluteWindowSize reserves nothing for it, so a layout that budgets for an inset bar comes out that many pixels wider than in Studio. |
A ScrollingFrame gives its children no growth ceiling on an axis whose canvas can grow. That is
what lets the usual scrolling list, an AutomaticSize column inside an AutomaticCanvasSize
frame, actually scroll. The bar is drawn from the same window and canvas sizes your components
read.
AutomaticSize on a ScrollingFrame that also sets CanvasSize is not implemented yet. It won’t error, and it won’t size the way Studio does.
Layout and modifier properties
| Instance | Supported | Accepted / partial |
|---|---|---|
uilistlayout | FillDirection, HorizontalAlignment, VerticalAlignment, SortOrder, Padding, HorizontalFlex, VerticalFlex, Wraps | — |
uigridlayout | CellSize, CellPadding, FillDirection, FillDirectionMaxCells, HorizontalAlignment, VerticalAlignment, SortOrder | StartCorner: only TopLeft. The other three fall back to it. |
uitablelayout | MajorAxis, Padding, FillEmptySpaceColumns, FillEmptySpaceRows, HorizontalAlignment, VerticalAlignment, SortOrder | See UITableLayout. |
uipagelayout | FillDirection, Padding, Circular, HorizontalAlignment, VerticalAlignment, SortOrder | Accepted: Animated, TweenTime, EasingStyle, EasingDirection and the gamepad/touch/scroll input flags. Page changes are instant. See UIPageLayout. |
uiflexitem | FlexMode (Grow / Shrink / Fill / Custom), GrowRatio, ShrinkRatio | See flex. |
uipadding | PaddingTop, PaddingBottom, PaddingLeft, PaddingRight | A scale inset resolves against the node’s own size on a real axis, and against zero on an AutomaticSize axis. Text measurement follows the same rule. |
uisizeconstraint | MinSize, MaxSize | — |
uiaspectratioconstraint | AspectRatio, DominantAxis | AspectType: ScaleWithParentSize is not implemented. |
uicorner | CornerRadius, TopLeftRadius, TopRightRadius, BottomLeftRadius, BottomRightRadius | A per-corner radius overrides CornerRadius for that corner, so a card can round only its top. The UIStroke ring and UIShadow follow the radius. |
uistroke | Color, Thickness, Transparency, Enabled, BorderStrokePosition | Outer (default) spreads outward, Inner insets into the object, Center straddles the edge. Enabled = false or a fully transparent stroke paints nothing. ApplyStrokeMode: the ring is always border-style, so Contextual on a text class doesn’t outline glyphs. |
uigradient | Color, Transparency, Rotation, Enabled | Offset is ignored. Color multiplies BackgroundColor3, as in the engine, so a transparent background stays transparent. Transparency fades the node’s own background, image and text, not its children. |
uishadow | Color, Offset, BlurRadius, Spread, Transparency, Enabled | A CSS drop shadow under the UIStroke ring. Only the first UIShadow is read, so ZIndex has nothing to order. Inset and Mode are not typed. |
uiscale | Scale | — |
Flex grows and shrinks
UIListLayout’s Fill flex shrinks as well as grows. A line that doesn’t wrap and holds more than
its container is compressed to fit. So is a UIFlexItem set to Shrink, or to Custom with a
ShrinkRatio.
This is what the trailing-icon idiom relies on: size the middle item {1, iconWidth} and let Fill
pull the line back in.
- Any other
UIFlexItemkeeps its size, and an item never shrinks below itsUISizeConstraint.MinSize. - A list that wraps wraps instead of shrinking. A row with no width of its own, or an automatic scrolling canvas, runs on.
- The overflow is split in proportion to each item’s size times its shrink ratio, as in CSS flexbox. Roblox doesn’t document its split, so this isn’t confirmed against the engine.
- A
TextWrappedlabel in a shrunk item wraps at the room the row leaves it.
Grow ratios are read per child. A UIFlexItem with GrowRatio = 0 keeps its size in a Fill
row, so a checkbox’s label stays beside the box. Only a child with no UIFlexItem follows the
list’s Fill.
UIListLayout and UIGridLayout report AbsoluteContentSize after layout, only when it changes. A
control that sizes itself from Change={{ AbsoluteContentSize }}, such as a dropdown, gets a real
number.
SortOrder defaults to Name
Every UIGridStyleLayout defaults SortOrder to Name, as the engine does. A list whose
children have distinct Names flows alphabetically, not in source order. The sort is stable, so
a tree that never sets Name keeps source order.
To order by LayoutOrder, set SortOrder={Enum.SortOrder.LayoutOrder}.
UITableLayout
The layout’s siblings are the table’s lines: rows, or columns under MajorAxis.ColumnMajor. Each
line’s children are its cells:
<frame Size={UDim2.new(1, 0, 0, 120)}> <uitablelayout Padding={UDim2.new(0, 8, 0, 4)} FillEmptySpaceColumns={true} /> <frame Name="Row1"> <textlabel Text="Region" Size={UDim2.fromOffset(120, 26)} /> <textlabel Text="Players" Size={UDim2.fromOffset(100, 26)} /> </frame></frame>- A column is as wide as its widest cell, and a row as tall as its tallest.
- Cells measure against the table’s content box, so a
0.25scale cell is a quarter of the table, not of its row. - A line spans the whole table on its minor axis. Its own
Sizeand anyUIPaddingon it are ignored. FillEmptySpaceColumnsandFillEmptySpaceRowsscale the tracks proportionally to span the container. A table that overruns is squeezed by the same rule.- A hidden cell takes neither a track nor a gap.
UIPageLayout
Pages keep their own Size and sit one container-plus-Padding apart along FillDirection, so a
parent with ClipsDescendants shows exactly one. Change the page by calling methods through a ref,
as in Roblox:
const pager = useRef<{ Next(): void; CurrentPageIndex: number }>();
<frame Size={UDim2.new(1, 0, 0, 90)} ClipsDescendants={true}> <uipagelayout ref={(instance) => { pager.current = instance as never; }} Padding={UDim.new(0, 16)} Circular={true} /> {/* …pages… */}</frame>;JumpToIndex(i), JumpTo(page), Next() and Previous() all work and fire PageLeave, then
PageEnter, then Stopped. Circular decides whether Next and Previous wrap at the ends.
CurrentPage reads back as the page instance. The layout engine itself reads CurrentPageIndex, a
0-based number the runtime keeps in step.
Outside the @rbxts/react adapter, set CurrentPageIndex on the node yourself.
Instance API
Every mounted object is a real instance with Roblox’s reflection surface, so a ref behaves as it
does in a place.
| Group | What is there |
|---|---|
| Identity | ClassName, Name, Parent, IsA, GetFullName |
| Tree | GetChildren, GetDescendants, FindFirstChild (with recursive), FindFirstChildOfClass, FindFirstAncestor, FindFirstAncestorOfClass, FindFirstAncestorWhichIsA, IsDescendantOf |
| Lifetime | Destroy, ClearAllChildren, Clone with Archivable, and the Destroying / ChildAdded / ChildRemoved / AncestryChanged signals. Destroy fires the ancestry signals, then locks Parent, as the engine does. |
| Change notification | GetPropertyChangedSignal(name) and Changed, which passes the property name. Fires for Parent and the Absolute* properties too. Doesn’t fire when a value type is set to an equal value, such as the same UDim2. |
| Geometry | AbsolutePosition / AbsoluteSize, written after each layout pass and signalled only when they change. |
| Attributes | GetAttribute, SetAttribute, GetAttributes, GetAttributeChangedSignal, AttributeChanged. See Attributes. |
TextBox | CaptureFocus, ReleaseFocus, IsFocused. A Changed handler that rewrites the text in the same keystroke is reflected in the box, so a validator that rejects a character removes it. |
BindableEvent | Event and Fire, scoped to that class. |
WaitForChild does not yield. It returns the child if it already exists, and otherwise warns
instead of blocking the frame. Code that waits for a child built later in the same render needs
restructuring.
A property read before it is written returns a typed default, as Roblox reflection does: 0 for a
number, "" for a string, and the class’s default for a datatype. Never undefined.
Attributes
Attributes work as they do in a place. An attribute is not readable as a property, doesn’t fire
Changed, and never reaches the renderer. Setting one paints nothing.
const player = Players.LocalPlayer;
player.GetAttributeChangedSignal("ColorScheme").Connect(() => { print(player.GetAttribute("ColorScheme"));});
player.SetAttribute("ColorScheme", "dark"); // firesplayer.SetAttribute("ColorScheme", "dark"); // unchanged — silent, as in Robloxplayer.SetAttribute("ColorScheme", undefined); // removes it, and still firesGetAttributes() returns a snapshot, not the live store. Names are validated as the engine does:
up to 100 letters, digits and underscores, with the RBX prefix reserved. A name Roblox would
refuse throws here too.
Input
Pointer and keyboard input go through the real runtime, not DOM shims. Activated,
MouseButton1Click, MouseButton1Down, MouseButton1Up, MouseButton2Click, MouseMoved,
InputBegan / InputChanged / InputEnded, UserInputService, focus and TextBox editing all
behave as in Roblox, including input sinking.
Keyboard input reaches the runtime, so UserInputService.IsKeyDown and KeyCode comparisons see
what the user pressed. Enum.KeyCode includes the digits, modifiers and gamepad buttons.
Only TextButton, ImageButton, TextBox, ScrollingFrame and anything with Active = true sink
pointer input. A transparent Frame is click-through, as in Roblox.
Active controls sinking, not hearing. A plain Frame with an InputBegan handler, such as a
slider handle, is hit-testable whether or not it is Active. A frame with no listeners stays
click-through, so a transparent positioning layer doesn’t swallow clicks.
What this list is not
This page describes loom 0.13.2. It is not a compatibility promise. Loom is pre-1.0, and an
Accepted row is a gap that can close without a breaking change. When a preview and Studio
disagree and the property isn’t listed here, treat Studio as correct and
file an issue.