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:
| Property | Description |
|---|---|
bounds read-only | The extent of the whole screen, in pt |
scale read-only | How many pixels one pt corresponds to |
nativeBounds read-only | The extent of the physical screen, in pixels |
nativeScale read-only | How many pixels one pt corresponds to on the physical screen |
traitCollection read-only | The screen's traits |
Brightness:
| Property | Description |
|---|---|
brightness | Screen brightness, 0 to 1 |
wantsSoftwareDimming | Whether to dim further in software below the hardware's minimum brightness |
Refresh and display:
| Property | Description |
|---|---|
maximumFramesPerSecond read-only | Maximum frames per second |
calibratedLatency read-only | Display hardware latency, in seconds |
currentEDRHeadroom read-only | How many times brighter than normal white the brightest white can be right now |
potentialEDRHeadroom read-only | How many times brighter than normal white the brightest white can be at most |
referenceDisplayModeStatus read-only | The status of reference display mode |
Recording and mirroring:
| Property | Description |
|---|---|
isCaptured read-only | Whether it is being recorded, cast, or mirrored right now |
mirroredScreen read-only | Which screen this screen is mirroring |
Display modes (for external displays):
| Property | Description |
|---|---|
availableModes read-only | All supported display modes |
preferredMode read-only | The most suitable display mode |
currentMode | The display mode in use right now |
Instance methods
| Method | Description |
|---|---|
snapshotViewAfterScreenUpdates() | Captures the screen's current contents as a view |
Events
| Event | When it fires |
|---|---|
brightnesschange | The screen brightness changed |
capturedchange | Recording, casting, or mirroring started or stopped |
modechange | The display mode changed |
referencedisplaymodestatuschange | The status of reference display mode changed |
keyboardshow | The keyboard is about to appear |
keyboardhide | The keyboard is about to be dismissed |
keyboardchange | The 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
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 2736Maximum brightness while showing a QR code
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
| ObjC | JS |
|---|---|
UIScreen.mainScreen | scene.screen |
view.window.windowScene.screen | view.window.windowScene.screen |
screen.bounds.size.width | screen.bounds.width |
screen.brightness = 1.0 | screen.brightness = 1 |
screen.isCaptured | screen.isCaptured |
UIScreenCapturedDidChangeNotification | screen.addEventListener('capturedchange', …) |
UIScreenBrightnessDidChangeNotification | screen.addEventListener('brightnesschange', …) |
UIScreenModeDidChangeNotification | screen.addEventListener('modechange', …) |
UIScreenReferenceDisplayModeStatusDidChangeNotification | screen.addEventListener('referencedisplaymodestatuschange', …) |
UIKeyboardWillShowNotification | screen.addEventListener('keyboardshow', …) |
UIKeyboardWillHideNotification | screen.addEventListener('keyboardhide', …) |
UIKeyboardWillChangeFrameNotification | screen.addEventListener('keyboardchange', …) |
See also
UIWindowScene: the screen is read from the sceneUIScreenMode: display modes- Traits: dark or light, screen scale
- Units: pt and pixels
UIDevice: device and system information