ui/resolution

Provides resolution independence utilities for responsive applications.

This module enables applications to adapt to different screen resolutions, orientations, and aspect ratios. It includes support for screen rotation scenarios, allowing applications to dynamically adjust their layout and scaling when device orientation changes.

Key features:

Automatic detection of a screen type based on resolution
Dynamic font-size calculation for different resolutions
Support for screen rotation and orientation changes
Configurable behavior via ui/resolutionui/resolution.config
CSS class generation for resolution-specific styling via ui/resolutionui/resolution.getResolutionClasses
The default export is an object containing the resolution independence methods.

Key exports include:

ui/resolutionui/resolution.config - Configuration object for controlling resolution behavior, screen rotation handling, and more
ui/resolutionui/resolution.getResolutionClasses - Returns CSS classes for resolution, orientation, and aspect ratio
ui/resolutionui/resolution.ResolutionDecorator - HOC for wrapping components with resolution support
Other utility functions for scaling, unit conversion, and screen type detection

Members

ResolutionDecorator Higher-Order Component

A higher-order component that configures resolution support for its wrapped component tree.

This decorator automatically applies resolution-specific CSS classes to the wrapped component, enabling responsive layouts that adapt to different screen sizes, orientations, and aspect ratios. It also supports dynamic updates when the window is resized or when the screen rotates.

Configuration options:

dynamic: true - when true, updates the resolution classes when the window resizes or the screen rotates
screenTypes: null - defines a set of screen types to support

Example:

// Will have the resolution classes and will be updated when the window resizes or the screen rotates
const AppWithResolution = ResolutionDecorator(App);
// Will have the resolution classes for the screen at the time of render only
const AppWithStaticResolution = ResolutionDecorator({dynamic: false}, App);
const AppWithScreenTypes = ResolutionDecorator({screenTypes: [
	{name: 'hd', pxPerRem: 16, width: 1280, height: 720, aspectRatioName: 'hdtv', base: true}
]}, App);

Configuration

dynamic

Boolean

Attaches an event listener to the window to listen for resize events.

When enabled, the resolution classes will be automatically updated when the window is resized or when screen rotation occurs (such as when a device changes from landscape to portrait orientation).

Default: true

screenTypes

Array(Object)

An array of objects containing declarations for screen types to add to the list of known screen types.

Default: null

calculateFontSize Function

calculateFontSize( type ) → String

Calculate the base rem font size.

This is how the magic happens. This accepts an optional screenType name. If one isn't provided, the currently detected screen type is used. When the workspace is smaller than the matched screen type in both dimensions, the base font size is scaled proportionally based on the workspace height. This scaling is gated by the config options fontSizeHandling (landscape orientation) and orientationHandling (portrait orientation, such as after screen rotation); when the relevant option is set to 'scale' the size is calculated dynamically, otherwise the screen type's pxPerRem value is used directly.

To use, put the following in your application code:

import ri from '@enact/ui/resolution';

ri.config.orientationHandling = 'scale';
ri.init();

This configuration is particularly useful for applications that support screen rotation and need to maintain consistent scaling when the device orientation changes from landscape to portrait or vice versa.

1 Param

type String: Screen type to base size the calculation on. If no screen type is provided, the current screen type will be used.

Returns

String: The calculated pixel size (with unit suffix. Ex: "24px").

config

defineScreenTypes Function

defineScreenTypes( types ) → undefined

Sets up screen resolution scaling capabilities by defining an array of all the screens being used.

These should be listed in order from smallest to largest, according to width.

The name, pxPerRem, width, and aspectRatioName properties are required for each screen type in the array. Setting base: true on a screen type marks it as the default resolution, upon which everything else will be based.

Executing this method also initializes the rest of the resolution-independence code.

Example:

import ri from 'enact/ui/resolution';

ri.defineScreenTypes([
	{name: 'vga',     pxPerRem: 8,  width: 640,  height: 480,  aspectRatioName: 'standard'},
	{name: 'xga',     pxPerRem: 16, width: 1024, height: 768,  aspectRatioName: 'standard'},
	{name: 'hd',      pxPerRem: 16, width: 1280, height: 720,  aspectRatioName: 'hdtv'},
	{name: 'uw-hd',   pxPerRem: 16, width: 1920, height: 804,  aspectRatioName: 'cinema'},
	{name: 'fhd',     pxPerRem: 24, width: 1920, height: 1080, aspectRatioName: 'hdtv', base: true},
	{name: 'uw-uxga', pxPerRem: 24, width: 2560, height: 1080, aspectRatioName: 'cinema'},
	{name: 'qhd',     pxPerRem: 32, width: 2560, height: 1440, aspectRatioName: 'hdtv'},
	{name: 'wqhd',    pxPerRem: 32, width: 3440, height: 1440, aspectRatioName: 'cinema'},
	{name: 'uhd',     pxPerRem: 48, width: 3840, height: 2160, aspectRatioName: 'hdtv'},
	{name: 'uhd2',    pxPerRem: 96, width: 7680, height: 4320, aspectRatioName: 'hdtv'}
]);

1 Param

types Array(Object): An array of objects containing screen configuration data, as in the preceding example.

Returns

undefined

getAspectRatio Function

getAspectRatio( type ) → Number

Calculates the aspect ratio of the specified screen type.

If no screen type is provided, the current screen type is used.

1 Param

type String: Screen type whose aspect ratio will be calculated. If no screen type is provided, the current screen type is used.

Returns

Number: The calculated screen ratio (e.g., 1.333, 1.777, 2.333, etc.)

getAspectRatioName Function

getAspectRatioName( type ) → String

Returns the name of the aspect ratio for a specified screen type, or for the default screen type if none is provided.

1 Param

type String: Screen type whose aspect ratio name will be returned. If no screen type is provided, the current screen type will be used.

Returns

String: The name of the screen type's aspect ratio

getResolutionClasses Function

getResolutionClasses( type ) → String

Returns the CSS classes for the given type.

This function generates CSS class names that can be used to style components based on the current screen resolution, orientation, and aspect ratio. The returned classes are particularly useful for responsive layouts and handling screen rotation scenarios.

The following CSS classes are returned:

Orientation class: enact-orientation-landscape or enact-orientation-portrait
- Applied based on the current screen orientation
- Updates automatically when device rotation occurs (if dynamic mode is enabled)
Resolution class: enact-res-{screentype}
- Examples: enact-res-fhd, enact-res-uhd, enact-res-hd, enact-res-qhd
- Applied based on the matched screen type
Aspect ratio class: enact-aspect-ratio-{aspectRatioName}
- Examples: enact-aspect-ratio-hdtv, enact-aspect-ratio-cinema, enact-aspect-ratio-standard
- Applied based on the screen type's aspect ratio name

Example return value: 'enact-orientation-landscape enact-res-fhd enact-aspect-ratio-hdtv'

1 Param

type String default: screenType: Screen type

Returns

String: CSS class names

getRiRatio Function

getRiRatio( type ) → Number

Returns the ratio of pixels per rem for the given type to the pixels per rem for the base type.

1 Param

type String default: screenType: Screen type

Returns

Number: ratio

getScreenType Function

getScreenType( rez ) → String

Fetches the name of the screen type that best matches the current screen size.

The best match is defined as the screen type that is the closest to the screen resolution without going over. ("The Price is Right" style.)

1 Param

rez Object: Optional measurement scheme. Must include height and width properties.

Returns

String: Screen type (e.g., 'fhd', 'uhd', etc.)

getUnitToPixelFactors Function

getUnitToPixelFactors( type ) → Number

Returns the pixels per rem for the given type.

1 Param

type String default: screenType: Screen type

Returns

Number: pixels per rem

init Function

init( args ) → undefined

This will need to be re-run any time the screen size changes, so all the values can be re-cached.

1 Param

args Object default: {}: A hash of options. The key measurementNode is used to as the node, typically the root element, to measure and use as the dimensions for the screenType.

Returns

undefined

linearScalingType

scale Function

scale( px ) → Number

Takes a provided pixel value and performs a scaling operation based on the current screen type.

1 Param

px Number: The quantity of standard-resolution pixels to scale to the current screen resolution.

Returns

Number: The scaled value based on the current screen scaling factor

scaleToRem Function

scaleToRem( pixels ) → String  |  undefined

Shorthand for when you know you need to scale some pixel value and have it converted to "rem" for proper scaling.

This runs ui/resolutionui/resolution.scale and ui/resolutionui/resolution.unit together.

1 Param

pixels Number: The quantity of standard-resolution pixels to scale to rems

Returns

String | undefined: Resulting conversion or, in case of malformed input, undefined

selectSrc Function

selectSrc( src ) → String

Selects the ideal image asset from a set of assets, based on various screen resolutions: HD (720p), FHD (1080p), UHD (4k).

When a src argument is provided, selectSrc() will choose the best image with respect to the current screen resolution. src may be either the traditional string, which will pass straight through, or a hash/object of screen types and their asset sources (keys:screen and values:src). The image sources will be used when the screen resolution is less than or equal to the provided screen types.

Example:

// Take advantage of the multi-res mode
import {Image} from '@enact/ui/Image';

const src = {
    'hd': 'http://lorempixel.com/64/64/city/1/',
    'fhd': 'http://lorempixel.com/128/128/city/1/',
    'uhd': 'http://lorempixel.com/256/256/city/1/'
};
...
<Image src={src} ... />
...

1 Param

src String | ui/resolutionui/resolution.selectSrcSrcOptions: A string containing a single image source or a key/value hash/object containing keys representing screen types ('hd', 'fhd', 'uhd', etc.) and values containing the asset source for that target screen resolution.

Returns

String: The chosen source, given the string or hash provided

unit Function

unit( pixels, toUnit ) → String  |  undefined

Convert to various unit formats.

Useful for converting pixels to a resolution-independent measurement method, like "rem". Other units are available if defined in the ui/resolutionui/resolution.unitToPixelFactors object.

Example:

import ri from '@enact/ui/resolution';

// Do calculations and get back the desired CSS unit.
var frameWidth = 250,
    frameWithMarginInches = ri.unit( 10 + frameWidth + 10, 'in' ), // '2.8125in' == frameWithMarginInches
    frameWithMarginRems = ri.unit( 10 + frameWidth + 10, 'rem' ); // '22.5rem' == frameWithMarginRems

2 Params

pixels String | Number: The pixels or math to convert to the unit ("px" suffix in String format is permitted. ex: '20px')

toUnit String: The name of the unit to convert to.

Returns

String | undefined: Resulting conversion in CSS safe format, in case of malformed input, undefined

unitToPixelFactors Object

Object that stores the pixel conversion factors to each keyed unit.

Type Definitions

LinearScalingConfig Object

• active

Boolean

Enables linear scaling calculation for font sizes and unit conversions. Default: true.

• type

ui/resolution.linearScalingType

Determines the reference screen used for linear scaling calculation. Default: linearScalingType.currentScreen.

ResolutionConfig Object

Configuration options for resolution independence behavior.

• fontSizeHandling

'normal' | 'scale'

Determines how to calculate font-size. When set to 'scale' and the screen is in landscape orientation, calculates font-size linearly based on screen resolution. When set to 'normal', the font-size will be the pxPerRem value of the best match screen type. Default: 'scale'

• orientationHandling

'normal' | 'scale'

Determines how to handle screen orientation and rotation. When set to 'scale' and the screen is in portrait orientation (due to screen rotation), dynamically calculates the base font size based on proportional scaling. When set to 'normal', uses the standard pxPerRem value. This is particularly useful for supporting device rotation scenarios. Default: 'normal'

• linearScaling

LinearScalingConfig

Configuration for linear scaling mode.

selectSrcOptions Object

The default configurable options for ui/resolutionui/resolution.selectSrc. Additional resolutions may be added.

• hd

String

HD / 720p Resolution image asset source URI/URL

• fhd

String

FHD / 1080p Resolution image asset source URI/URL

• uhd

String

UHD / 4K Resolution image asset source URI/URL