Principles

The rules the library is built on, and what they mean for the code you write.

A handful of rules shape every decision in the library. Knowing them helps you predict how an API will look before you open its reference page.

Apple's SDK is the source of truth

Nobody maintains a list of components or modifiers by hand. The generator discovers every view, modifier and value type in the SwiftUI that ships with Xcode, and decides how to expose each one from its declaration.

For you: if SwiftUI has it and it can be represented safely, it's here, with the same parameters. When Apple adds an API, it shows up after the next generation, without anyone writing a wrapper first.

Keep Apple's names

The API uses SwiftUI's names, argument labels and order wherever JavaScript allows. It only adapts where the language forces it to.

  • Initializer parameters become props with the same labels: VStack(alignment:spacing:) becomes alignment and spacing.
  • Enum cases become strings: .leading becomes 'leading'.
  • Modifiers keep their names and apply in the order you chain them, as in Swift.
  • Overloads stay overloads. The arguments you pass decide which one runs.

For you: Apple's documentation, WWDC sessions and Swift examples translate directly. Read Reading the reference for the exact rules.

Statically typed, compiled ahead of time

Every component and modifier has real Swift behind it that calls SwiftUI through its typed API, the same way a Swift app would. Nothing looks up methods by name or uses reflection while your app runs. All of it compiles into your app in the normal native build.

For you: you get the same behaviour and performance as hand-written SwiftUI. If a modifier is in the reference, it's in your binary.

One tree, one layout contract

React decides the tree. Fabric mounts it, SwiftUI draws and measures its views, and Yoga lays out the React content around them. Each piece has one job, and none of them competes with another for layout.

That rules out the usual workarounds: separate React roots inside native views, serializing the component tree to JSON, or passing sizes around by hand.

For you: React components can sit inside SwiftUI views, and SwiftUI views inside React components, at any depth. State changes update only what changed.

Honest coverage

Not every SwiftUI API can be expressed in React, and the library doesn't pretend it can. Each API is sorted into one of three groups:

GroupWhat it means
GeneratedIt maps directly onto React and is generated in full
Needs an adapterIt needs some hand-written native support, such as an unusual closure or generic. The generator writes everything it can around that
UnsupportedIt can't be represented safely. It's left out instead of shipped half-working

The reference only lists what you can use, with the iOS version each API needs.

Reproducible

The same SDK always produces the same library, byte for byte. Each update changes exactly what Apple changed in the SDK, and nothing else.

For you: upgrading is predictable. A new release reflects a new SDK or a fix, never an accident of the build.