Livewire Component
Tapix ships a standalone Livewire component that renders the full import wizard. Use it to embed the wizard in any Blade view outside of Filament.
Basic Usage
<livewire:tapix.wizard
:importer-class="App\Importers\ContactImporter::class"
:return-url="route('contacts.index')"
:sample-file="asset('samples/contacts.csv')"
/>
Mount Props
importerClass (required)
The fully qualified class name of the importer to use. This determines which fields, validation rules, and relationships are available during the import.
returnUrl (optional)
A URL to redirect to when the user cancels the import. Must be a relative path. Prefixes with // are rejected for security to prevent open redirect attacks.
returnUrl only accepts relative paths (e.g., /contacts). Absolute URLs and protocol-relative URLs (//example.com) are rejected to prevent open redirect vulnerabilities.sampleFile (optional)
A URL pointing to a sample CSV or XLSX file. When provided, the upload step displays a download link so users can grab a correctly formatted template before uploading their own data.
Wizard Steps
The wizard guides users through four sequential steps:
- Upload (STEP_UPLOAD) -- Upload a CSV or XLSX file for processing.
- Map Columns (STEP_MAP) -- Match columns from the uploaded file to the fields defined in the importer.
- Review Values (STEP_REVIEW) -- Review parsed data and fix validation errors inline before importing.
- Preview & Import (STEP_PREVIEW) -- Preview the final changes and execute the import.
State Persistence
The wizard persists its state using a ?import= query parameter containing a ULID. If a user navigates away and returns to the same URL, the wizard resumes from where they left off using the stored session data.
Step Navigation
Users can navigate back to any previously completed step but cannot skip ahead to future steps. Once the import begins executing, backward navigation is disabled to prevent data inconsistencies.
Start Over
A "Start Over" action is available throughout the wizard. It presents a confirmation dialog before resetting the wizard state and deleting the current import data. After confirmation, the wizard returns to the upload step.
Import Lock
Once the import process starts, the wizard enters a locked state. In this state, backward navigation is disabled and the user can only monitor progress or wait for completion.
Events
onUploadCompleted(storeId, rowCount, columnCount)
Fired after the uploaded file has been parsed and stored. Receives the store identifier, the number of rows detected, and the number of columns detected.
import-started
A Livewire event dispatched when the import execution begins. Listen for this event to trigger UI updates or notifications in other components on the page.