Firstlight UI Documentation

Firstlight is the app-shell layer for NativePHP. Install it with Laravel Boost, and you or your coding agent have what a standard forms app needs: lists and detail, search, forms with Laravel validation, settings, sheets and dialogs, and feedback.

Every control is a genuine SwiftUI control on iOS and a Jetpack Compose Material 3 control on Android. One Blade API becomes the right pattern on each platform. Navigation chrome comes from NativePHP's own native chrome, and VoiceOver, TalkBack, larger text, right-to-left layout, and Reduce Motion reach every control the way they reach the platform's own apps.

Start with a recipe

Each recipe is a complete screen you can copy. Each one runs unchanged in the showcase app, whose Pest tests exercise it. Build the list and detail flow first: it is the app shell the other recipes run inside.

• Build a list and detail flow — Give the app a native navigation shell with a list screen that pushes a detail screen.
• Build a searchable list screen — Search, paginate, refresh, open, and delete records from one native List.
• Build a large list screen — Scroll thousands of local records with a virtual list that builds only the visible rows.
• Build a form screen — Validate with a Form Request, show field and form-level errors, and save with Feedback.
• Build a settings screen — Group switches and pickers in native sections that save on change.
• Build a photo upload screen — Crop, validate, and save a photo to a model only when the user taps Save.
• Build an app lock screen — Hide the app in the app switcher, lock it after time away, and unlock with Face ID, Touch ID, or a fingerprint.

Get started

• Installation — Install Firstlight and Laravel Boost, and make the native renderers available to a NativePHP application.
• Build with a coding agent — What the Boost guideline, the firstlight-init and building-firstlight-screens skills, and llms.txt give your agent.
• Add your first component — Add a complete Segmented control with server-backed state.
• Theming — Configure the semantic NativePHP theme tokens inherited by Firstlight components.

Laravel on native screens

• Validate fields — Show Laravel validation messages on Firstlight fields with validate(), validateOnly(), and Form Requests.
• Submit forms — Validate Firstlight fields, run a PHP action once, and publish success Feedback.
• Authorize actions — Hide, disable, or guard Firstlight actions with Laravel Gate and Policy decisions.
• Paginate lists — Bind Laravel paginators to List pull-to-refresh and end-reached.
• Destroy list items — Authorize Confirmation Dialog deletion of List rows by stable keys.
• Test screens — Scaffold a screen with make:firstlight-screen and test fields, lists, dialogs, and Feedback with Native::test().
• Localize chrome — Override Firstlight-owned chrome labels and inherit application locale and timezone for Date and Time pickers.

Understand Firstlight

• What Firstlight is — The app-shell layer for NativePHP: what Firstlight provides, what NativePHP and Mobile UI provide, and what Firstlight is not.
• Accessibility — What VoiceOver, TalkBack, larger-text, right-to-left, and Reduce Motion users get, what is tested, what is still unverified, and what your app owns.
• SuperNative components — Understand how an EDGE component becomes genuine platform UI.
• Server-authoritative state — Understand interaction, PHP acceptance, and native reconciliation.

Components

• Activity Indicator — Communicate indeterminate native activity with semantic sizes and one polite appearance announcement.
• Button — Look up labelled actions, semantic variants, loading and disabled states, accessibility, and adapter behaviour.
• Callout — Present persistent semantic messages with one optional labelled action.
• Transient Feedback — Publish queued app-level outcomes with semantic tones, optional actions, and automatic or held lifetime.
• Badge — Present compact display-only counts or short markers with semantic tones and contextual accessibility.
• Checkbox — Configure strict Boolean form and checklist state with server-authoritative proposals.
• Choice Group — Configure visible single-radio or multiple-checkbox choice rows with stable values.
• Media — Capture one image or document into Storage with optional crop and ValidatesFields.
• Alert Dialog — Present one native acknowledgement with a single action.
• Confirmation Dialog — Ask for one native confirmation with explicit cancellation and destructive action semantics.
• Modal — Present authored content in a full-screen native overlay with server-controlled dismissal.
• Bottom Sheet — Present authored content in a native bottom sheet with server-controlled dismissal.
• Date Picker — Choose strict nullable calendar dates with inclusive bounds and native confirmation.
• Time Picker — Choose strict nullable wall-clock times with localized native confirmation.
• Icon Button — Configure compact icon-only actions, platform icon overrides, semantic variants, states, and accessibility.
• List Item — Configure tappable application rows with leading identity, trailing affordances, disabled behaviour, and platform icon overrides.
• List — Compose finite vertical collections of List Item rows with optional grouped sections and refresh or pagination hooks.
• List Section — Group List Item rows with optional headers and footers inside a parent List.
• Pill Group — Configure compact single- or multiple-selection native options.
• Progress — Communicate determinate or indeterminate work with strict values and native accessibility.
• Segmented — Look up the Segmented control's complete public contract and platform evidence.
• Tabs — Switch between sections of one object with stable values, counts, and native tab semantics.
• Search Field — Configure native query entry, clear, submission, and synchronisation behaviour.
• Select — Choose one stable string or integer value with automatic searchable presentation for larger option sets.
• Slider — Choose one strictly validated numeric value from an evenly spaced native range.
• Stepper — Increment or decrement an exact bounded number while PHP remains authoritative.
• Status Label — Look up display-only status text, semantic tones, accessibility, and platform evidence.
• Metric — Display one labelled value with tabular figures, optional detail and grouped accessibility.
• Text Field — Configure native single-line editing, input hints, icons, and synchronisation.
• Text Area — Configure native multiline editing, line bounds, validation, accessibility, and synchronisation.
• Code Editor — Edit JSON, YAML, env, and plain text with native indentation, a key row, and follow mode for live logs.
• Switch — Configure native boolean settings, server-authoritative state, and accessibility.

Reference

• ValidatesFields — Look up the public validate() contract, MessageBag binding, and current limitations.
• Screen assertions — Look up the Firstlight Native::test() assertions and the make:firstlight-screen options.
• Compatibility — Check the currently supported PHP, NativePHP, iOS, Android, and Swift versions.