Exporting

Introduction

Tables can be exported to different formats such as CSV, Excel, and PDF. Before continuing, make sure you have installed the Laravel Excel package. You can install it via composer:

composer require maatwebsite/excel

Defining Exports

The Table class has an exports() method that can be used to define all the export options. Simply create an Export instance with the static make() method and return it from the exports() method.

use InertiaUI\Table\Table;

class Users extends Table
{
    public function exports(): array
    {
        return [
            Export::make(),
        ];
    }
}

By default, the export is set to the Excel type and has a label of Excel Export. The make() method accepts five arguments to customize the export:

use Maatwebsite\Excel\Excel;

Export::make(
    label: 'CSV Export',
    filename: 'users.csv',
    type: Excel::CSV,
    authorize: true,
    events: []
);

The type must be one of the constants from the Maatwebsite\Excel\Excel class. Note that some types, like PDF, require additional configuration.

Filtering and Selected Rows

By default, the export will include all rows, even if you have applied filters or selected rows in the frontend. You can change this behavior by passing the limitToFilteredRows or limitToSelectedRows options to the make() method.

Export::make(
    limitToFilteredRows: true,
    limitToSelectedRows: true,
);

Alternatively, you can call the limitToFilteredRows() or limitToSelectedRows() methods.

Export::make()
    ->limitToFilteredRows()
    ->limitToSelectedRows();

If you want this to be the default for all tables, you may call the static defaultLimitToFilteredRows() and defaultLimitToSelectedRows() methods on the Table class, for example, in your AppServiceProvider:

use InertiaUI\Table\Export;

Export::defaultLimitToFilteredRows();
Export::defaultLimitToSelectedRows();

Authorization

Authorization works the same way as with Row Actions. The authorize option can be a boolean or a Closure.

Export Events

The events array enables you to hook into the underlying package events.

use Maatwebsite\Excel\Events\BeforeExport;

Export::make(events: [
    BeforeExport::class => function (BeforeExport $event) {
        $event->writer->getProperties()->setCreator('John Doe');
    },
]);

Check out the documentation for more information.

Customizing Exports

You can customize how each column is exported.

Column Mapping

If you want to change the content of a column when exporting, you can pass a Closure to the exportUsing argument. Alternatively, you can call the exportUsing() method.

TextColumn::make('reference', exportAs: function (string $reference) {
    return "#REF-{$reference}";
});

The closure accepts a second argument, which is the Model instance.

TextColumn::make('name')->exportAs(function (string $name, User $user) {
    return $user->is_active ? $name : "Inactive: {$name}";
});

Column Formatting

You may choose a custom format for each column by passing a Closure or string to the exportFormat argument. Alternatively, you can call the exportFormat() method.

use PhpOffice\PhpSpreadsheet\Style\NumberFormat;

TextColumn::make('amount', exportFormat: NumberFormat::FORMAT_CURRENCY_USD_SIMPLE);

TextColumn::make('amount')->exportFormat(NumberFormat::FORMAT_CURRENCY_USD_SIMPLE);

Column Styling

You can customize the column styling by passing a Closure or array to the exportStyle argument. Alternatively, you can call the exportStyle() method.

use PhpOffice\PhpSpreadsheet\Style\Style;

TextColumn::make('name', exportStyle: ['font' => ['bold' => true]]);

TextColumn::make('email')->exportStyle(function (Style $style) {
    $style->getFont()->setBold(true);
});

Exclude Columns

To exclude a column from being exported, pass false to the exportAs argument, or call the dontExport() method.

TextColumn::make('Name', exportAs: false);

TextColumn::make('Name')->dontExport();

Define a Custom Export

If you need more control over the export, you can write your own logic to export the data. You can do this with the using argument or the using() method.

use App\Tables\Users;
use InertiaUI\Table\Export;
use InertiaUI\Table\Http\ExportRequest;
use Illuminate\Contracts\Database\Eloquent\Builder;

Export::make()->using(function (Users $table, Export $export, ExportRequest $request, Builder $query) {
    // return response()->download(...);
});

If the export uses the limitToFilteredRows or limitToSelectedRows options, those will already be applied to the given Query Builder ($query). You may also pass an invokable class:

Export::make(using: new CustomUserExport);

Custom Export with Redirect Response

The using() callback expects a downloadable response, but if you want to redirect the user to a different page, you can call the asDownload() method with false.

Export::make()
    ->asDownload(false)
    ->using(function () {
        return to_route('dashboard');
    });

Alternatively, you can pass a URL to the redirectBackWithDialog() method to stay on the same page and show a dialog.

Export::make()->redirectBackWithDialog();

// With custom title and message
Export::make()->redirectBackWithDialog(
    title: 'Exporting your data',
    message: 'The export is being processed.'
);

Queued Exports

If you have a large dataset, you may want to queue the export and notify the user when it is ready. You can do this by calling the queue() method.

Export::make()->queue(
    filename: 'data-export.xlsx',
    disk: 's3'
);

Instead of downloading the file, the user will see a dialog with a message indicating that the export is being processed. You can customize the title and message of the dialog by passing the title and message options.

Export::make()->queue(
    filename: 'data-export.xlsx',
    disk: 's3',
    title: 'Exporting your 2024 data',
    message: 'The export is being processed.'
);

Besides the dialog, you may want to inform the user when the export is ready, for example, by sending an email. You can interact with the queued job by passing a Closure to the withQueuedJob argument or by calling the withQueuedJob() method.

Export::make()->queue()->withQueuedJob(function ($job) {
    $job->chain([
        new SendExportNotification(auth()->user()),
    ]);
});

Likewise, you can set the queue or delay for the job:

Export::make()->queue(
    withQueuedJob: fn ($job) => $job->onQueue('exports')->delay(now()->addMinutes(5))
);

Default Job Configuration

Instead of passing a disk and queue name to each export, you may use the static defaultQueueName() and defaultQueueDisk() methods on the Export class. For example, you can use them in your AppServiceProvider:

use InertiaUI\Table\Export;

Export::defaultQueueName('exports');
Export::defaultQueueDisk('s3');

Custom Redirect on Queued Export

If you don't want to show the dialog to the user and instead want to redirect them to a different page, you can pass a URL to the redirect option. You can pass a string, a RedirectResponse, or a Closure. There's also a redirectToRoute helper method.

Export::make()
    ->queue()
    ->redirect('/exports')
    ->redirect(to_route('exports.index'))
    ->redirect(fn () => route('exports.index'))
    ->redirectToRoute('exports.index');

Data Attributes

You can add Data Attributes to the Export button by using the dataAttributes argument in the make() method or by using the dataAttributes method. You don't have to prefix the keys with data-.

Export::make()->dataAttributes([
    'contents' => 'all-users',
]);

Targetting Exports with CSS

You can target the Export button with specific data attributes using CSS. For example, to style the Export with the data-content="all-users" attribute, you can use the following CSS:

a[data-content="all-users"] {
    /* ... */
}

Metadata

You can add metadata to Exports by using the meta argument in the make() or by using the meta() method.

Export::make()->meta([
    'key' => 'value',
]);

In the default Table component, this metadata is unused and not passed to any DOM element. However, this feature can be useful when extending the Table component using slots, or when you build a custom Table component.