[Update] October 21, 2025
[Update] September 26, 2025
Hi Creators!
We’re excited to introduce a new API today in Studio beta: ViewportDisplaySize! This adaptive property makes it easy to build responsive, cross-platform UI by helping you tailor your UI to the physical viewing size of a player’s screen. The API categorizes the physical size of a player’s screen into Small, Medium, or Large classifications.
Our goal is to make cross-platform development as seamless as possible. ViewportDisplaySize helps you create a great user experience on any device and decouples design from inputs, whether it’s a phone, a tablet, a laptop, or a TV, without having to guess the display size based on resolution.
During this Studio beta period, you can’t publish live experiences with ViewportDisplaySize (it will throw a warning). Once we release the ViewportDisplaySize to client, these will be available to use in-experience.
Keep reading to learn more!
Why is ViewportDisplaySize Important?
Designing UI for small screens vs. large screens provide different challenges – you need to account for factors like different text legibility and UI layouts, to name a few. Relying on screen resolution (or pixel counts) to make design choices is error-prone, since a 4K phone and a 4K TV have the same number of pixels but vastly different physical dimensions.
ViewportDisplaySize solves this by categorizing the physical viewport into Small, Medium, or Large classifications. This allows you to adapt your UI based on the actual space available, ensuring your creations look and feel great everywhere.
Note: This API should not be used to make decisions about rendering quality. We are continuously working on ensuring your UI renders at a high quality on all devices regardless of the screen’s pixel density.
How to Enable this Beta
Click here to learn more
To enable this beta in Roblox Studio, follow these simple steps:
- Open Roblox Studio and navigate to the “File” menu.
- Click on “Beta Features”.
- Enable the “New Display Size API” option by checking the corresponding checkbox (see screenshot below) and press Save.
- Restart Roblox Studio when prompted.
How to Use ViewportDisplaySize
ViewportDisplaySize is a read-only property that returns a set of opinionated breakpoints – a DisplaySize enum of Small, Medium, or Large – based on the internally-fetched size of the viewport that the Roblox client is running on.
While device classes can have ranges of display sizes, they generally follow this categorization:
| Enum | Summary |
|---|---|
| Small | Most tablet/mobile/handheld devices |
| Medium | Most laptops and monitors |
| Large | Most TVs or larger |
Note that the viewport may not always fill the entire screen – say for example, when the Roblox client is confined to half of a laptop display.
Here’s an example of how you could use ViewportDisplaySize in a LocalScript in your experience to manage different UI states:
local GuiService = game:GetService("GuiService")
local function updateUI()
if (GuiService.ViewportDisplaySize == Enum.DisplaySize.Small) then
-- Update UI to small screen
elseif (GuiService.ViewportDisplaySize == Enum.DisplaySize.Large) then
-- Update UI to large screen
else
-- Update UI to medium/default screen
end
end
GuiService:GetPropertyChangedSignal("ViewportDisplaySize"):Connect(updateUI)
updateUI()
Check out our sample placefile for one example of how UI can change depending on display size:
ViewportDisplaySize.rbxl (67.5 KB)
For more native customization, you can use the UI Style Editor (currently in Studio Beta) to configure themes for the various DisplaySize enums. Create tokens and themes for text sizes, container sizes, and any other sizing/measurement tokens to suit your needs. These can be dynamically swapped at run-time using the pseudocode structure above.
Made with love
Special thanks to @LittleEel0621, @ProtoValence, and @MetaVars for their hard work in making this happen! We can’t wait to see the UI you create. Let us know if you have any feedback or questions.
