ScreenOrientation

Read the orientation

GetOrientationType / GetAngle

The current orientation as a strongly-typed ScreenOrientationType (portrait/landscape, primary/secondary), plus the rotation angle in degrees.

var type = await screenOrientation.GetOrientationType();
var angle = await screenOrientation.GetAngle();

// e.g. LandscapePrimary at 0 degrees on a desktop monitor

Live sample

read orientation output

Results will appear here when you interact with the samples.

Lock & unlock

Lock / Unlock

Locks the containing document to one of the OrientationLockType values, and releases the lock again. Ideal for games or video players that only make sense in landscape.

await screenOrientation.Lock(OrientationLockType.Landscape);

// release the lock and return to the default behavior:
await screenOrientation.Unlock();

Live sample

Lock type

lock output

Results will appear here when you interact with the samples.

Change event

SubscribeChange

Fires whenever the screen orientation changes - for example when the user rotates their phone. The handler receives an OrientationState carrying the new type and angle.

var subscription = await screenOrientation.SubscribeChange(state =>
{
    // state.Type  → ScreenOrientationType.PortraitPrimary, ...
    // state.Angle → 0, 90, 180, 270
});

// 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.

// register and keep the id
var id = await screenOrientation.AddChange(OnOrientationChanged);

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

// or drop every registered listener at once
await screenOrientation.RemoveAllChanges();

Locking needs mobile or fullscreen Orientation locking is typically only honored on mobile devices, and on many browsers only while the document is in fullscreen mode. On a desktop browser Lock usually rejects with a NotSupportedError - the demo above surfaces that error in the output console.

Best experienced on a phone Open this page on a mobile device and rotate it after subscribing to the change event to watch the type and angle update live.

API reference

Member

Signature

Description

GetOrientationType

Task<ScreenOrientationType> GetOrientationType()

Returns the document's current orientation type (portrait/landscape, primary/secondary).

GetAngle

Task<ushort> GetAngle()

Returns the document's current orientation angle in degrees.

Lock

Task Lock(OrientationLockType lockType)

Locks the orientation of the containing document to the specified orientation.

Unlock

Task Unlock()

Unlocks the orientation of the containing document from its default orientation.

AddChange

ValueTask<Guid> AddChange(Action<OrientationState> handler)

Registers a handler for the orientation change event and returns its listener id.

SubscribeChange

ValueTask<ButilSubscription> SubscribeChange(Action<OrientationState> handler)

Subscribe variant of AddChange returning a disposable subscription handle.

RemoveChange

ValueTask<Guid[]> RemoveChange(Action<OrientationState> 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.

InvokeScreenOrientationChange

void InvokeScreenOrientationChange(Guid id, ushort angle, string type)

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.