Skip to content

UIScreen ​

UIScreen represents a screen: its size, pixel density, brightness, refresh rate, and whether it is being recorded right now.

Read the screen from a scene: scene.screen. An iPhone has only one screen, and every scene reads that one. With an external display connected, scenes shown on that display read a different screen. External displays are not verified in the simulator.

The screen's size is the extent of the whole screen, including the areas occupied by the status bar and the home indicator at the bottom. Lay out content using the view's safe area, not by calculating from the screen's size.

Inheritance: EventTarget → NSObject → UIScreen

Constructor ​

It cannot be created with new. new UIScreen() throws TypeError: Illegal constructor: UIScreen is created by the runtime, not by new. Read the screen from a scene's screen.

Instance properties ​

Also inherits the properties of NSObject.

Size and pixel density:

PropertyDescription
bounds read-onlyThe extent of the whole screen, in pt
scale read-onlyHow many pixels one pt corresponds to
nativeBounds read-onlyThe extent of the physical screen, in pixels
nativeScale read-onlyHow many pixels one pt corresponds to on the physical screen
traitCollection read-onlyThe screen's traits

Brightness:

PropertyDescription
brightnessScreen brightness, 0 to 1
wantsSoftwareDimmingWhether to dim further in software below the hardware's minimum brightness

Refresh and display:

PropertyDescription
maximumFramesPerSecond read-onlyMaximum frames per second
calibratedLatency read-onlyDisplay hardware latency, in seconds
currentEDRHeadroom read-onlyHow many times brighter than normal white the brightest white can be right now
potentialEDRHeadroom read-onlyHow many times brighter than normal white the brightest white can be at most
referenceDisplayModeStatus read-onlyThe status of reference display mode

Recording and mirroring:

PropertyDescription
isCaptured read-onlyWhether it is being recorded, cast, or mirrored right now
mirroredScreen read-onlyWhich screen this screen is mirroring

Display modes (for external displays):

PropertyDescription
availableModes read-onlyAll supported display modes
preferredMode read-onlyThe most suitable display mode
currentModeThe display mode in use right now

Instance methods ​

MethodDescription
snapshotViewAfterScreenUpdates()Captures the screen's current contents as a view

Events ​

EventWhen it fires
brightnesschangeThe screen brightness changed
capturedchangeRecording, casting, or mirroring started or stopped
modechangeThe display mode changed
referencedisplaymodestatuschangeThe status of reference display mode changed
keyboardshowThe keyboard is about to appear
keyboardhideThe keyboard is about to be dismissed
keyboardchangeThe keyboard's position or size is about to change: appearing, being dismissed, switching input methods
  • Events cannot be canceled.
  • Callbacks for the first four events do not run synchronously at the moment of the change but a little later; see How the runtime works.
  • The three keyboard events are dispatched on the spot: listeners run inside the keyboard's animation, so layout changes made then move along with the keyboard.
  • You can also listen for and dispatch events with custom names on a screen.

Examples ​

Reading the screen size ​

js
application.addEventListener('sceneconnect', (e) => {
  const screen = e.scene.screen;
  console.log(screen.bounds.width, screen.bounds.height, screen.scale);
  console.log(screen.nativeBounds.width, screen.nativeBounds.height);
});

Result: on the iPhone Air simulator (iOS 27.2), logs two lines:

420 912 3
1260 2736

Maximum brightness while showing a QR code ​

js
application.addEventListener('sceneconnect', (e) => {
  const screen = e.scene.screen;
  const before = screen.brightness;
  screen.brightness = 1;
  // Write it back when leaving this view controller
  // screen.brightness = before;
  console.log(before);
});

Effect: the screen goes to maximum brightness, and the console logs the original brightness. According to the iOS documentation, brightness reverts to the system setting after the device locks. The screen brightening is not verified in the simulator.

An example that covers sensitive content during recording is in capturedchange.

Corresponding iOS API ​

ObjCJS
UIScreen.mainScreenscene.screen
view.window.windowScene.screenview.window.windowScene.screen
screen.bounds.size.widthscreen.bounds.width
screen.brightness = 1.0screen.brightness = 1
screen.isCapturedscreen.isCaptured
UIScreenCapturedDidChangeNotificationscreen.addEventListener('capturedchange', …)
UIScreenBrightnessDidChangeNotificationscreen.addEventListener('brightnesschange', …)
UIScreenModeDidChangeNotificationscreen.addEventListener('modechange', …)
UIScreenReferenceDisplayModeStatusDidChangeNotificationscreen.addEventListener('referencedisplaymodestatuschange', …)
UIKeyboardWillShowNotificationscreen.addEventListener('keyboardshow', …)
UIKeyboardWillHideNotificationscreen.addEventListener('keyboardhide', …)
UIKeyboardWillChangeFrameNotificationscreen.addEventListener('keyboardchange', …)

See also ​