Comparison
Firstlight UI vs NativePHP Mobile UI
They are not alternatives. NativePHP Mobile UI is the native foundation; Firstlight UI is the app-shell layer installed alongside it. Mobile UI renders native controls from Blade. Firstlight adds the Laravel contracts NativePHP does not ship — screen-level validate(), a once-run submit(), and Gate-backed authorize().
You cannot use Firstlight without Mobile UI. The real decision is whether you want form, validation, and authorization behaviour from a package, or written per screen in your own app.
What each one is responsible for
| Concern | NativePHP Mobile UI | Firstlight UI |
|---|---|---|
| Role | The native foundation for NativePHP apps | The app-shell layer on top of it: controls, Laravel contracts, and recipes for a standard forms app |
| Relationship | Required. Firstlight depends on it | Installed alongside Mobile UI, never instead of it |
| Component coverage | Comprehensive native catalogue | 32 form, list, selection, overlay, status, and feedback controls — no charts or carousels |
| Navigation chrome | Native stacks, title bars, and tab bars come from NativePHP Mobile’s usesNativeChrome() layouts | Uses that same chrome and draws none of its own |
| Control contracts | Each control exposes its own platform-shaped API | One contract across every control — stable public value, and the same label, error, disabled, and required semantics |
| Rendering | SwiftUI on iOS, Jetpack Compose on Android | The same renderers, via Mobile UI’s extension points |
| Element tree | Publishes the shared EDGE element tree | Publishes into that same element tree |
| Theme | Supplies the semantic theme | Inherits it — no parallel theme to maintain |
| Screen-level validate() | Not provided | ValidatesFields — validate() and validateOnly() |
| Validation message display | @nativeError renders as sibling text; a thrown ValidationException reaches the generic overlay | Binds the first MessageBag message to the field’s native error slot |
| Guarded submit | A press is an ordinary PHP method; re-entry is yours to handle | SubmitsForms — validates, runs the action once, optionally sends success Feedback |
| Gate-backed authorize() | No Gate helpers on screens; an uncaught authorization exception opens the overlay | AuthorizesActions — allows(), denies(), authorize() hide, disable, or send danger Feedback |
| Licence and price | See the NativePHP project | MIT, free, no paid tier |
| Maturity | The established foundation | Stable 1.0.0 — tested on physical iOS and Android devices |
When to add Firstlight, and when to stay on Mobile UI alone
Add Firstlight when
- Your app has real forms, and you are writing the same validation and submit plumbing on every screen.
- You want Laravel validation messages to land on the native field rather than as sibling text or a generic overlay.
- You need Gate and Policy decisions to hide or disable native controls consistently.
- You want field semantics decided once across a codebase or a team.
Stay on Mobile UI alone when
- Your app is mostly display and navigation, with few or no forms.
- You need a native control outside Firstlight’s catalogue — reach for Mobile UI directly, and mix the two freely.
- You need a production-ready package and cannot take a release-candidate dependency.
Common questions
- Does Firstlight UI replace NativePHP Mobile UI?
- No. Firstlight is installed alongside NativePHP Mobile UI and depends on it. Mobile UI supplies the native foundation — the EDGE element tree, the SwiftUI and Jetpack Compose renderers, the semantic theme, and the event lifecycle. Firstlight adds the app-shell layer on top of it: form, list, dialog, and feedback controls, Laravel validation and authorization on screens, and tested recipes. Navigation chrome comes from NativePHP’s own native chrome, not from Firstlight.
- What does Firstlight add that NativePHP does not have?
- Consistent controls and screen-level PHP helpers. At the control level, every Firstlight component exposes a stable public value and the same field semantics — label, value, error, disabled, and required behave identically across text fields, selects, pickers, sliders, and choice groups, so a form does not need per-control special cases. At the screen level, NativePHP EDGE has no validate(), no once-run submit helper, and no Gate-backed action guard; Firstlight adds ValidatesFields, SubmitsForms, and AuthorizesActions, so validation messages bind to the native field error slot, submits run once and publish native Feedback, and Gate decisions hide or disable native controls instead of reaching the generic error overlay.
- Can I use Firstlight and NativePHP Mobile UI components on the same screen?
- Yes. Firstlight is built on Mobile UI’s ordinary component extension points and publishes into the same element tree, so Firstlight and Mobile UI components compose together and share the same theme and event lifecycle.
- What do I need to install Firstlight UI?
- Use NativePHP Mobile ^4.7 and Mobile UI ^0.9. Install firstlightui/nativephp with Composer, then extend FirstlightUI\NativeComponent for your screens. The installation guide has the complete setup.
- Is Firstlight UI free?
- Yes. Firstlight UI is open source and free to use, released under the MIT licence. There is no paid tier.
- Why is the Firstlight component catalogue smaller than Mobile UI’s?
- By design. Mobile UI aims for comprehensive native coverage. Firstlight covers what a standard forms app needs with 32 controls, and adds a control only when it has an equal native contract on iOS and Android. It has no charts, carousels, or custom-drawn controls, and it is not a design system.
- Does Firstlight work with AI coding agents?
- Yes, that is its main audience. Firstlight ships a Laravel Boost guideline and two skills, firstlight-init and building-firstlight-screens, that steer an agent to the tested recipes, and publishes its documentation as llms.txt and llms-full.txt.
- Is Firstlight UI production ready?
- Yes. Firstlight 1.0.0 is the first stable release. It has been tested on physical iOS and Android devices, including VoiceOver on iOS. Spoken TalkBack output and long-running performance tests have not been recorded yet.