Skip to content

Nacre API documentation ​

This is the reference for every API Nacre provides to JS, written for JS developers building apps with Nacre. Each page covers one class or one group of capabilities: what it represents, how to write it, what effect you get, and where it can go wrong.

If you're new to Nacre, read How the runtime works and application first, then look up other pages as needed. To build your own app from scratch, see the getting started guide.

What APIs there are ​

The APIs fall into two kinds:

  • Defined by the runtime itself: application, console, fetch, timers, local storage, WebView, and so on. Their names and usage are decided by Nacre.
  • iOS native classes: UIView, UILabel, CALayer, and so on, using their original iOS names directly; property and method names also correspond to Apple's documentation. The end of every class page and member page shows the corresponding ObjC code, so you can go from Apple's documentation to how to write it in JS.

Only what is listed under "Reference" below is available. iOS classes not listed (such as NSString or UITableView) don't exist in JS; reading their names throws ReferenceError, and there is no general way to call them.

Most APIs in the tables are available in every project. A few, such as location, taking photos, and Face ID, require installing a separate package; they are in the "Capability packages (installed separately)" group. For which ones need installing and what else to do after installing, see Core and capability packages. Your app's own native code and the capabilities of third-party native SDKs aren't here: they must first be wrapped as native modules and then called from application.nativeModules; see Writing your own native module.

How to read these docs ​

  • Each class has a class page: what it is, what it inherits from, and a list of all its properties, methods, and events, one sentence each. Each entry links to that member's own page: value, parameters, return value, what it throws, and examples.
  • For how to use these classes to get something done, see the guides.
  • The "Effect" or "Result" after each code sample describes what you see after running it. Anything marked "not verified in the simulator" hasn't been confirmed by actually running it; everything unmarked has been verified or comes directly from the code.
  • Lengths and coordinates are in points (pt); see Units.

Reference ​

Grouped by purpose, in the same order as the sidebar on the left. Each class page lists all members of the class, and each member has its own page.

Getting started ​

PageDescription
How the runtime worksNacre is a JavaScript runtime on iOS.
Core and capability packagesNacre's API is split into two parts: the core and capability packages.
Native classesNative classes represent the classes iOS provides: views (UIView), text labels (UILabel), view controllers (UIViewController), layers (CALayer), and so on.
UnitsIn Nacre's APIs, numeric units match iOS: lengths are in points (pt), angles in radians, and animation times in seconds.
StructsA struct represents one value made up of several numbers: a point, a size, a rectangle, a set of insets, a transform matrix.
EnumsAn enum is a value chosen from a fixed set of options.

App and events ​

PageDescription
ApplicationApplication represents the running app.
EventTargetEventTarget represents an object that can fire events and be listened to.
EventEvent represents an event: what happened (the event name), whom it was dispatched to, and whether it can be canceled.
ErrorEventErrorEvent represents an uncaught exception.
PromiseRejectionEventPromiseRejectionEvent represents a Promise rejection that wasn't handled.
OpenURLEventOpenURLEvent represents one occurrence of "this app was opened by a URL".
application.nativeModulesapplication.nativeModules represents all native modules registered in this app.
NativeModuleNativeModule represents a native module registered in the app: a piece of code written in ObjC or Swift that provides a set of methods and a set of events under a name.

Windows and view controllers ​

PageDescription
UIWindowSceneUIWindowScene represents one instance of the App's UI, called a scene.
UIWindowSceneGeometryUIWindowSceneGeometry represents a scene's geometry at a given moment: the interface orientation and whether the orientation is locked.
UIWindowSceneGeometryPreferencesIOSUIWindowSceneGeometryPreferencesIOS represents the preferences for a rotation request: which orientations you want.
UIStatusBarManagerUIStatusBarManager represents how a scene's status bar looks at the moment.
UISceneSessionUISceneSession represents a scene's session: the scene's persistent identity.
UIWindowUIWindow represents a window: the outermost view that hosts the interface in a scene.
UIViewControllerUIViewController represents the manager of one screen of content, called a view controller.
UINavigationControllerUINavigationController represents a stack of view controllers, called a navigation controller.
UINavigationItemUINavigationItem represents a view controller's configuration for the navigation bar: the title in the center, the subtitle, the text on the next view controller's back button, and which buttons are on the left and right.
UIBarItemUIBarItem represents the shared part of an item on a navigation bar or tab bar: text, icon, whether it can be tapped, and a tag number.
UIBarButtonItemUIBarButtonItem represents a button on the navigation bar.
UITabBarControllerUITabBarController represents an interface with a tab bar, called a tab bar controller.
UITabBarUITabBar represents the row of tabs at the bottom of the screen in a tab bar controller.
UITabBarItemUITabBarItem represents one tab in the bottom tab bar: the icon, the text below the icon, and the badge in the top-right corner.
UIAlertControllerUIAlertController represents a system alert: a title, a message, and some buttons.
UIAlertActionUIAlertAction represents a button on a system alert.
UIActivityViewControllerUIActivityViewController represents the system share sheet.

Views and layout ​

PageDescription
UIViewUIView represents a rectangular area on the screen, called a view.
NSLayoutConstraintNSLayoutConstraint represents a constraint: a relationship between two positions or sizes on two views, such as "the card's left edge is 16 pt to the right of the safe area's left edge" or "the two color blocks are equally wide".
NSLayoutAnchorNSLayoutAnchor represents a position or size on a view that constraints can refer to, called an anchor: an edge, a center line, a text baseline, a width, or a height.
NSLayoutXAxisAnchorNSLayoutXAxisAnchor represents a horizontal position anchor: leadingAnchor, trailingAnchor, leftAnchor, rightAnchor, or centerXAnchor on a view or layout guide.
NSLayoutYAxisAnchorNSLayoutYAxisAnchor represents a vertical position anchor: topAnchor, bottomAnchor, centerYAnchor, firstBaselineAnchor, and lastBaselineAnchor on a view or layout guide.
NSLayoutDimensionNSLayoutDimension represents a dimension anchor: the widthAnchor and heightAnchor of a view or layout guide, and the distance between two anchors returned by anchorWithOffsetToAnchor().
UILayoutGuideUILayoutGuide represents a rectangle that takes part in layout but isn't displayed, called a layout guide.
UIKeyboardLayoutGuideUIKeyboardLayoutGuide represents a layout guide for the area the keyboard occupies.
UIStackViewUIStackView represents a stack view, a container that arranges the subviews you put in it into a row or a column along one direction and automatically positions and sizes each of them.
UIScrollViewUIScrollView represents a view that can scroll, called a scroll view.
UIVisualEffectViewUIVisualEffectView represents an area with an effect.
UIVisualEffectUIVisualEffect represents a visual effect.
UIBlurEffectUIBlurEffect represents a blur effect: it blurs what is behind a visual effect view and covers it with a translucent layer of color.
UIVibrancyEffectUIVibrancyEffect represents a vibrancy effect: it makes text and icons placed over a blur pick up the colors of the content underneath, instead of being a flat layer of gray.
UIGlassEffectUIGlassEffect represents a glass effect, a new material in iOS 26.
UIGlassContainerEffectUIGlassContainerEffect represents a glass container effect (iOS 26): it draws several pieces of glass as a group, and pieces that are close enough merge together.
UIActivityIndicatorViewUIActivityIndicatorView represents an activity indicator (a spinner): a ring of short lines that keeps rotating, telling the user that something is in progress and has no result yet.
UIProgressViewUIProgressView represents a progress bar: a horizontal line with a filled portion starting from the left, whose length shows how much of a task is complete.
UIToolbarUIToolbar represents a toolbar: a horizontal bar with a number of buttons arranged from left to right.

Structs ​

PageDescription
CGPointCGPoint represents a point on a plane: the x-coordinate x and the y-coordinate y, in pt.
CGSizeCGSize represents a size: a width width and a height height, in pt.
CGRectCGRect represents a rectangle: the top-left position x, y plus the width width and height height, all in pt.
UIEdgeInsetsUIEdgeInsets represents how far each of the four edges is inset: top, left, bottom, right, in pt.
NSDirectionalEdgeInsetsNSDirectionalEdgeInsets represents how far each of the four edges is inset, with left and right distinguished by text direction: top, leading, bottom, trailing, in pt.
CGAffineTransformCGAffineTransform represents a two-dimensional affine transform: scaling, rotation, translation, and combinations of them.
CATransform3DCATransform3D represents a three-dimensional transform: scaling, rotation, and translation along the x, y, and z directions, perspective, and combinations of them.
CAFrameRateRangeCAFrameRateRange represents a frame rate range: minimum, maximum, and preferred (the rate you'd most like), all in frames per second.
NSRangeNSRange represents a range of text: length UTF-16 code units starting at location.

Lists ​

PageDescription
UICollectionViewUICollectionView represents a scrollable list.
UICollectionViewDiffableDataSourceUICollectionViewDiffableDataSource represents a list's data source: it decides which items a UICollectionView shows and what each item looks like.
NSDiffableDataSourceSnapshotNSDiffableDataSourceSnapshot represents an inventory of a list's data: which sections there are, which items are in each section, and in what order.
NSIndexPathNSIndexPath represents the position of an item in a list: item number item in section number section, both counted from 0.
UICollectionViewLayoutUICollectionViewLayout represents the object that decides how cells are arranged in a UICollectionView.
UICollectionViewCompositionalLayoutUICollectionViewCompositionalLayout represents a compositional layout: a layout object built from sections, groups, and items.
UICollectionLayoutListConfigurationUICollectionLayoutListConfiguration represents the configuration of a list layout: the list's appearance, whether separators are drawn between rows, the background color, and where section headers come from.
UICollectionReusableViewUICollectionReusableView represents a reusable view in a UICollectionView.
UICollectionViewCellUICollectionViewCell represents a cell: the on-screen view for one item in a UICollectionView.
UICollectionViewListCellUICollectionViewListCell represents the cell used in list layouts.
UIListContentConfigurationUIListContentConfiguration represents the content of one row in a list: primary text, secondary text, and an image on the left.

Text, images, and color ​

PageDescription
UILabelUILabel represents a piece of read-only text on screen, called a label.
UIFontUIFont represents a font.
UIImageUIImage represents an image.
UIImageViewUIImageView represents a view that displays an image, called an image view.
UIColorUIColor represents a color.
UITraitCollectionUITraitCollection represents a set of values describing the environment the UI is currently in: whether it's dark or light, how many pixels 1 pt covers on the screen, which level the user set the system text size to, and so on.
NSAttributedStringNSAttributedString represents styled text, called an attributed string: a string plus a set of attributes on each range.
NSMutableAttributedStringNSMutableAttributedString represents a mutable attributed string: you can add attributes to a range, remove attributes, and append, insert, replace, and delete text.
NSParagraphStyleNSParagraphStyle represents a set of paragraph styles: alignment, line spacing, paragraph spacing, indentation, and line breaking.
NSMutableParagraphStyleNSMutableParagraphStyle represents a set of paragraph styles that can be changed.
NSShadowNSShadow represents a text shadow: its offset, blur radius, and color.
NSTextAttachmentNSTextAttachment represents an attachment in an attributed string: an image shown in the position of one character.

Controls and input ​

PageDescription
UIControlUIControl represents a control: a view that receives touches and turns the course of a touch into a set of "control events" that it fires.
UIButtonUIButton represents a button: a tappable area on screen that displays a title, an image, or both.
UISwitchUISwitch represents a switch: a round thumb on a short track, off when the thumb is on the left and on when it is on the right.
UISliderUISlider represents a slider: a horizontal track with a round thumb that the user drags to pick a number within a range.
UIStepperUIStepper represents a stepper: a minus button and a plus button side by side.
UISegmentedControlUISegmentedControl represents a segmented control: a horizontal row of segments, each showing a title or an image, with at most one segment selected at a time.
UIPageControlUIPageControl represents a page indicator: a row of small dots, one per page, with the dot for the current page brighter.
UIDatePickerUIDatePicker represents a date picker: a system-provided control that lets the user choose a date, a time, or a duration.
UIColorWellUIColorWell represents a color well: a small round button showing the current color.
UITextFieldUITextField represents a single-line text field.
UITextViewUITextView represents an area where the user can type multiple lines of text.
NSTextContainerNSTextContainer represents the area where text is laid out in a UITextView: how much space each line leaves on the left and right, how many lines at most, and what to do when a line doesn't fit.
UISearchBarUISearchBar represents a search bar: a single-line text field with a magnifying-glass icon and a clear button at its right end.

Gestures ​

PageDescription
UIGestureRecognizerUIGestureRecognizer represents a gesture recognizer: an object attached to a view that watches the touches on that view and fires events when it recognizes a certain gesture.
UITapGestureRecognizerUITapGestureRecognizer represents a tap recognizer: it recognizes the gesture when a finger goes down and lifts quickly.
UILongPressGestureRecognizerUILongPressGestureRecognizer represents a long-press recognizer: it recognizes the gesture when a finger stays down without moving for a period of time, 0.5 seconds by default.
UIPanGestureRecognizerUIPanGestureRecognizer represents a pan (drag) recognizer: it recognizes the gesture when a finger touches down and moves.
UIPinchGestureRecognizerUIPinchGestureRecognizer represents a pinch gesture recognizer: it recognizes two fingers spreading apart or pinching together.
UIRotationGestureRecognizerUIRotationGestureRecognizer represents a rotation recognizer: it recognizes the gesture when two fingers turn around each other.
UISwipeGestureRecognizerUISwipeGestureRecognizer represents a swipe recognizer: it recognizes the gesture when a finger moves quickly across the screen in a given direction.
UIScreenEdgePanGestureRecognizerUIScreenEdgePanGestureRecognizer represents a screen-edge pan gesture recognizer: it only recognizes drags that start at the edge of the screen and move inward.

Layers and animation ​

PageDescription
CALayerCALayer represents a layer: a rectangular area on screen, plus the content drawn in that area.
CAGradientLayerCAGradientLayer represents a gradient layer: it draws a color gradient within its own rectangle.
CAShapeLayerCAShapeLayer represents a shape layer: it draws a path (UIBezierPath).
UIBezierPathUIBezierPath represents a path: a geometric shape made of connected line segments, curve segments, and arcs.
CAAnimationCAAnimation represents an animation applied to a layer: over a period of time, it changes one of the layer's properties (opacity, position, corner radius, color, path, and so on) continuously from one value to another.
CAPropertyAnimationCAPropertyAnimation represents an animation that changes one property of a layer.
CABasicAnimationCABasicAnimation represents an animation that changes one property of a layer from one value to another.
CAKeyframeAnimationCAKeyframeAnimation represents an animation that makes one of a layer's properties pass through several values in turn, or that moves a layer along a path.
CASpringAnimationCASpringAnimation represents an animation that brings a property to its end value the way a spring does: the property overshoots the end value, bounces back a few times, and settles.
CAAnimationGroupCAAnimationGroup represents a group of animations.
CAMediaTimingFunctionCAMediaTimingFunction represents a timing function.
CATransactionCATransaction represents a transaction: a group of layer changes handed to the system together.
CADisplayLinkCADisplayLink represents a timer synchronized with screen refreshes.
NSRunLoopNSRunLoop represents a thread's event loop.

Networking ​

PageDescription
fetch()The fetch() function sends an HTTP request and returns a Promise.
RequestRequest represents an HTTP request: the URL, method, headers, body, and the signal used to cancel it, kept in one object.
ResponseResponse represents the response to an HTTP request: the status code, the response headers, and the response body.
HeadersHeaders represents a set of HTTP request or response headers.
BlobBlob represents an immutable chunk of binary data.
ReadableStreamReadableStream represents data that can be read out one chunk at a time.
ReadableStreamDefaultReaderReadableStreamDefaultReader represents a reader for a stream: it holds the stream's lock and reads chunk by chunk with read().
AbortControllerAbortController represents the side that issues a cancellation.
AbortSignalAbortSignal represents an abort signal: whether it has been aborted and why.
URLURL represents a parsed address.
URLSearchParamsURLSearchParams represents the query parameters after the ? in a URL.
WebSocketWebSocket represents a persistent connection between the app and a server.
application.networkapplication.network represents the device's network status at this moment: whether it is connected to a network, which kind of network it uses, and whether that network is metered.

Web content ​

PageDescription
WebViewWebView represents a view that displays a web page.
WebContentsWebContents represents the web page inside a WebView.
NavigationHistoryNavigationHistory represents a web page's back and forward navigation: whether it can go back or forward, and going back or forward one page.
WebContentsIPCWebContentsIPC represents the app's end of a web page's request-response channel.
ipcRendereripcRenderer represents the web page's end of the message channel: the page uses it to send messages to the app, ask the app for results, and receive messages from the app.
contextBridgecontextBridge is the entry point a preload script uses to put things on the web page: it attaches a set of methods written in the preload script to the page's window, so the page's scripts can call them.
SessionSession represents a storage partition: cookies, localStorage, IndexedDB, caches, and other data left by web pages in a WebView are all stored in some partition.
CookiesCookies represents all the cookies in one storage partition.
CookieCookie represents a record of a cookie at one moment.

Runtime globals ​

PageDescription
TimersTimers are a set of global functions for running a callback after a period of time, or repeatedly at an interval.
performancePerformance represents a clock used only to measure durations.
Intl.NumberFormatIntl.NumberFormat represents a formatting object that writes numbers as text according to the conventions of a region.
Intl.DateTimeFormatIntl.DateTimeFormat represents a formatter that writes a moment in time as text, following the conventions of a given locale.
NSLocaleNSLocale represents a locale: a language, plus a country or region, and the formats that go with them — currency, decimal and grouping separators, calendar, quotation marks, and metric or imperial units.
cryptoCrypto represents the system's source of random numbers.
TextEncoderTextEncoder represents an encoder that encodes strings into UTF-8 bytes.
TextDecoderTextDecoder represents a decoder that turns UTF-8 bytes into a string.
Text, bytes, and deep copiesText, bytes, and deep copies: this group of global APIs converts between strings and bytes, and deep-copies values.

Storage ​

PageDescription
application.storageapplication.storage represents the app's key-value storage.
application.fileSystemapplication.fileSystem represents the app's own file storage.
NSBundleNSBundle represents a bundle: a directory on disk that holds a program and its resources.

System features ​

PageDescription
UIDeviceUIDevice represents the device the app is running on.
UIScreenUIScreen represents a screen: its size, pixel density, brightness, refresh rate, and whether it is being recorded right now.
UIScreenModeUIScreenMode represents one display mode of a screen: a resolution and a pixel shape.
UIPasteboardUIPasteboard represents the system clipboard.
UIFeedbackGeneratorUIFeedbackGenerator represents a haptic feedback generator.
UIImpactFeedbackGeneratorUIImpactFeedbackGenerator represents an impact feedback generator: the tap of vibration when two things collide, such as a button being pressed, a card snapping into place, or a dragged item hitting a boundary.
UISelectionFeedbackGeneratorUISelectionFeedbackGenerator represents a selection feedback generator: a very light tap of vibration when the selection moves from one item to another, such as a picker wheel turning one notch, a slider passing a tick mark, or the selected row of a list changing.
UINotificationFeedbackGeneratorUINotificationFeedbackGenerator represents a notification-type haptic feedback generator: the vibration for when something succeeded, needs attention, or failed.

Capability packages (installed separately) ​

PageDescription
application.keychainapplication.keychain represents the app's items in the keychain.
LAContextLAContext represents one authentication that confirms "the person holding the phone right now is its owner".
CLLocationManagerCLLocationManager represents an entry point through which the app asks the system for location.
CLLocationCLLocation represents a location measured by the system: latitude and longitude, altitude, the error of each measurement, speed, direction of movement, and when the location was measured.
CLLocationCoordinate2DCLLocationCoordinate2D represents the latitude and longitude of a point on Earth, in degrees.
CLLocationErrorCLLocationError is the Error object you get when location fails.
UNUserNotificationCenterUNUserNotificationCenter represents the entry point between this app and the system's notification features; there is only one per app.
UNNotificationRequestUNNotificationRequest represents a notification to be sent: an identifier, the content, and when to deliver it.
UNNotificationContentUNNotificationContent represents the read-only content of a notification, read from a request's content, including those of delivered notifications and remote push notifications.
UNMutableNotificationContentUNMutableNotificationContent represents the content of a notification you write yourself: title, subtitle, body, badge, sound, group identifier, and data that travels with the notification.
UNNotificationSoundUNNotificationSound represents the sound played when a notification arrives.
UNNotificationTriggerUNNotificationTrigger represents when a notification is delivered.
UNTimeIntervalNotificationTriggerUNTimeIntervalNotificationTrigger represents a trigger that delivers "after a number of seconds".
UNCalendarNotificationTriggerUNCalendarNotificationTrigger represents a trigger that delivers "at the moment matching these date components".
UNPushNotificationTriggerUNPushNotificationTrigger indicates that a notification arrived as a remote push: sent by a server through Apple's push service to the phone.
UNNotificationUNNotification represents a notification that has been delivered.
UNNotificationResponseUNNotificationResponse represents an action the user took on a notification, such as tapping it.
UNNotificationSettingsUNNotificationSettings represents this app's notification settings at a given moment: whether the user allows notifications, and whether each setting — sound, badge, lock screen, Notification Center, and so on — is on.
RemoteNotificationsRemoteNotifications represents this app's remote notifications: registering with Apple's push service, getting this device's token, and receiving silent pushes.
PushEventPushEvent represents a silent push that has arrived.
UIImagePickerControllerUIImagePickerController represents the system's camera interface.
PHPickerViewControllerPHPickerViewController represents the system's photo picker.
PHPickerConfigurationPHPickerConfiguration represents the configuration of the photo picker: how many items can be selected at most, which types are shown, how selection works, and what the picker looks like.
PHPickerFilterPHPickerFilter represents which kinds of items a photo picker shows, for example only images, only videos, or images without screenshots.
PHPickerResultPHPickerResult represents one item the user picked in the photo picker.
NSItemProviderNSItemProvider represents a provider for one item of content.
PHPhotoLibraryPHPhotoLibrary represents the system photo library.
CNContactPickerViewControllerCNContactPickerViewController represents the system's contact picker.
CNContactCNContact represents a contact in the address book: name, company, phone numbers, email addresses.
CNLabeledValueCNLabeledValue represents one phone number or one email address of a contact, together with its label.
CNPhoneNumberCNPhoneNumber represents a phone number.
CNContactPropertyCNContactProperty represents the item the user selected in a contact's details: which value of which field of which contact.
CNContactFormatterCNContactFormatter joins a contact's name into one line.
ATTrackingManagerATTrackingManager represents the user's answer to "may this app track me", and is responsible for asking the user for it.
ASIdentifierManagerASIdentifierManager gives this device's advertising identifier.

The current JS global environment ​

globalThis has 65 own properties, and all of them are non-enumerable (as ECMAScript requires). So Object.keys(globalThis) returning an empty array doesn't mean the environment is empty; use Object.getOwnPropertyNames to see them.

Available: the complete ES standard library, and a fairly recent version of it — Iterator (iterator helpers), DisposableStack / AsyncDisposableStack / SuppressedError (explicit resource management), Float16Array, Atomics, SharedArrayBuffer, WeakRef, and FinalizationRegistry are all there. Promise and the microtask queue work normally. eval and new Function are available as usual.

Non-standard globals installed by the runtime: console, EventTarget / Event (and ErrorEvent, PromiseRejectionEvent), application, and the native classes and struct classes listed above.