loading

Dimensions

GetWidth / GetHeight

The full width and height of the screen in pixels, regardless of what the operating system or browser occupies.

C#
var width = await screen.GetWidth();
var height = await screen.GetHeight();
Live sample
dimensions output
Results will appear here when you interact with the samples.

Available area

GetAvailableWidth / GetAvailableHeight

The screen area actually available to windows, excluding permanent or semipermanent OS interface features such as the Windows Taskbar or the macOS Dock.

C#
var availableWidth = await screen.GetAvailableWidth();
var availableHeight = await screen.GetAvailableHeight();
Live sample
available area output
Results will appear here when you interact with the samples.

Color & pixel depth

GetColorDepth / GetPixelDepth

The color depth and bit depth of the screen, in bits per pixel. On virtually all modern hardware both report 24 or 30.

C#
var colorDepth = await screen.GetColorDepth();
var pixelDepth = await screen.GetPixelDepth();
Live sample
depth output
Results will appear here when you interact with the samples.

Multiple displays

IsExtended

Reports whether the user's desktop spans more than one screen - useful before offering multi-window or presentation features.

C#
var isExtended = await screen.IsExtended();
Live sample
multiple displays output
Results will appear here when you interact with the samples.

Change event

SubscribeChange

Fires when the screen changes in some way - width or height, available area, color depth or orientation. The returned subscription detaches the listener when disposed.

C#
var subscription = await screen.SubscribeChange(() =>
{
    // width, height, color depth or orientation changed
});

// later, when no longer needed:
await subscription.DisposeAsync();
Live sample
change event output
Results will appear here when you interact with the samples.

Manual listener management

AddChange / RemoveChange / RemoveAllChanges

If you prefer explicit ids over disposable subscriptions, AddChange returns a Guid that can later be passed to RemoveChange, and RemoveAllChanges drops every listener registered on this instance.

C#
// register and keep the id
var id = await screen.AddChange(OnScreenChange);

// remove a single listener by id
await screen.RemoveChange(id);

// or drop every registered listener at once
await screen.RemoveAllChanges();
Warning:
Browser support varies IsExtended and the screen change event belong to the newer Window Management surface and are currently available in Chromium-based browsers only. The size and depth properties work everywhere.
Note:
Prerendering During prerender/SSR there is no JS runtime, so all getters return their default value (0 or false) instead of throwing. If you branch on a result, defer the read to OnAfterRenderAsync.

API reference

Member
Signature
Description
GetWidth
Task<float> GetWidth()
Returns the width of the screen in pixels.
GetHeight
Task<float> GetHeight()
Returns the height of the screen in pixels.
GetAvailableWidth
Task<float> GetAvailableWidth()
Returns the amount of horizontal space in pixels available to the window.
GetAvailableHeight
Task<float> GetAvailableHeight()
Returns the height of the screen minus permanent OS interface features such as the Taskbar.
GetColorDepth
Task<byte> GetColorDepth()
Returns the color depth of the screen.
GetPixelDepth
Task<byte> GetPixelDepth()
Returns the bit depth of the screen.
IsExtended
Task<bool> IsExtended()
Returns true if the user's device has multiple screens, and false if not.
AddChange
ValueTask<Guid> AddChange(Action handler)
Registers a handler for the screen change event and returns its listener id.
SubscribeChange
ValueTask<ButilSubscription> SubscribeChange(Action handler)
Subscribe variant of AddChange returning a disposable subscription handle.
RemoveChange
ValueTask<Guid[]> RemoveChange(Action handler)
Removes listeners matched by delegate identity; pass the exact handler instance that was registered.
RemoveChange
ValueTask RemoveChange(Guid id)
Removes a single change listener by its id.
RemoveAllChanges
ValueTask RemoveAllChanges()
Removes every change listener registered on this instance.
InvokeScreenChange
void InvokeScreenChange(Guid id)
JS interop bridge invoked by the browser on the change event; not intended for application code.
DisposeAsync
ValueTask DisposeAsync()
Removes all listeners and releases the interop reference.
GetAvailableLeft
Task<float> GetAvailableLeft()
X-coordinate of the left edge of the available screen area. Non-standard; reported as 0 where unimplemented, which is indistinguishable from a genuine 0.
GetAvailableTop
Task<float> GetAvailableTop()
Y-coordinate of the top edge of the available screen area - the height of any OS bar docked at the top. Same non-standard caveat as GetAvailableLeft.
An unhandled error has occurred. Reload 🗙