List

Description

The "List" module purpose - render list of some records from your database to work with them.

When the resolved list has no rows, Adminix renders a single No records found. table row. The empty state uses the same table width and responsive scroll container as regular records, including relation manager child lists.

1. Configuration

2. Lenses

3. Quick filters and chips

4. Fields

5. Row details

6. Row reorder

7. Column visibility

8. Table summaries

9. Grouped rows

10. Density and sticky table controls

11. Saved table views

12. Searching

13. Filters

14. Reset controls

15. Mobile behavior

16. Soft-delete row actions

17. Clone actions

18. Bulk actions

19. Actions

20. New item link

21. Appearance examples

Configuration

Basic example:

To add to the page List module you need paste AlexKudrya\Adminix\Modules\List\ListModule class instance as an argument to addModule or addModules method of AdminixPage object.

ListModule configuration

Full settings list:

Lenses

Lenses are server-defined saved views for ListModule. They are useful for common list presets such as Active, Drafts, Deleted, VIP, or Needs review.

The active lens is selected by the query key lens-{moduleName}. Adminix resolves this value only against lenses configured in PHP. Unknown lens names are ignored and the default list is rendered.

Lens criteria are applied after base ListModule::criteria() and before user filters, search, and sorting. Lens filters are defaults for configured list filters. Use the filter field as the key:

Result: when the URL contains lens-users=needs-review and does not contain filter-users-status, Adminix applies status = pending and shows the filter as selected. If the URL already contains filter-users-status, the request value wins and the lens default is not used. Date range defaults can use a nested from/to map or flat keys such as created_at-from. Lens sorting is a default sorting only: if the request contains a valid sort-{module}-{field} parameter, the user-selected sorting wins. Pagination links keep the active lens query parameter.

Use base criteria() for mandatory tenant/user scoping. Use lenses only for alternate server-owned views inside that scope.

Quick filters and chips

Quick filters are small server-defined shortcuts for frequent list states. They do not introduce a separate query language. Each quick filter can set defaults for configured list filters, the list search query, and an existing lens.

The active quick filter is selected by the query key quick-{moduleName}. Adminix resolves this value only against ListQuickFilter instances configured in PHP. Unknown quick filter names are ignored.

Filter defaults use the same keys as ListLens::filters(). For date ranges, call range($field, $from, $to) or pass ['created_at' => ['from' => '2026-01-01', 'to' => '2026-01-31']] to filters().

Precedence is:

• explicit request search/filter/lens values;

• active quick filter defaults;

• active lens default filters.

Result: clicking a quick filter renders the preset button as active, applies only server-configured filters/search/lens, and shows removable chips for the active quick filter, lens, search, and filter values. When a chip represents an explicit URL parameter, its remove link deletes that parameter. When a value came from a quick filter or lens default, the remove link clears the preset source instead.

Saved table views can persist quick-{moduleName} only when it references a configured quick filter. resetControls() clears active quick filters along with search, filters, lens, sorting, and pagination. Reorder handles remain disabled while a quick filter is active, because the visible rows are filtered.

Use quick filters for operator convenience, not tenant or authorization boundaries. Mandatory scoping still belongs in criteria(), policies, guards, relation context, or app-side query criteria. adminix:doctor warns when a quick filter references missing filter fields, missing lenses, invalid filter values, or has no effect.

Fields

Fields is an array, of fields to be rendered in the List.

To add Field to the List module you need paste AlexKudrya\Adminix\Modules\List\ListField class instance as an argument to addField or addFields method of ListModule object.

Row details

Use ListRowDetails when a list needs a compact primary row plus expandable read-only metadata. Adminix renders one toggle column and a hidden detail row for every visible record. The detail panel is prepared from the same server-side list datasource, base criteria, active lens, filters, search, sorting, pagination, and optional relation scope used for the rendered table.

ListRowDetails supports:

• make($title = null)/title() for an optional detail heading;

• columns(1..4) for the read-only field grid;

• addField()/addFields() with DetailField or another ResourceField subclass;

• expanded() to render all detail rows initially open, otherwise they are collapsed and toggled with JavaScript.

Row details do not add a write endpoint and do not trust browser-owned datasource, criteria, field names, or primary keys. Password fields are rendered without stored values, matching resource/detail password safety. Keep sensitive tenant, owner, credential, and internal audit columns out of row details unless they are intentionally visible to the admin user.

ListField configurations

Row reorder

reorderable($orderField) enables flat drag-and-drop ordering for a ListModule. It renders a left-side grip handle, disables user-driven column sorting for that list, and uses the configured base Sorting as the canonical row order. If the module does not already have sorting, reorderable('sort_order') configures Sorting::field('sort_order')->direction('asc') automatically.

Result: Adminix shows a grip column for reorderable rows only when the whole current reorder scope is visible. Drag the grip with a pointer or focus it and use ArrowUp/ArrowDown. The browser sends only the ordered primary keys and a signed context; Adminix resolves page, module, datasource, criteria, primary key, order field, and relation scope from server-side configuration.

Reorder handles are intentionally hidden when the visible scope cannot be written predictably:

• the list has pagination enabled;

• the URL contains current-list search, quick filter, filters, lens, sort, or page state;

• the primary key is not rendered in the list data;

• fewer than two rows are visible;

• the module does not have one ascending base sort by the reorder field.

• in tree mode, a visible row points to a parent outside the current visible row set.

For standard Eloquent and query-builder data sources, the built-in writer uses a transaction and keeps the existing order-value set. It moves one row to a temporary sentinel value outside the current datasource range, rotates the affected cycle, and then assigns the existing values to the new row order. This avoids immediate unique-index collisions on databases that do not support deferrable unique constraints, while also avoiding permanent growth of the order values after repeated reorders. The current scope must have unique numeric order values.

Adminix does not automatically normalize order values to 1..N. Normalization can collide with unknown global or composite unique constraints, tenant scopes, category scopes, or non-SQL storage rules. If an application wants periodic normalization, implement it in application code where the full uniqueness scope and storage semantics are known.

Use treeReorderable($orderField, $parentField = 'parent_id', $rootParentValue = null) for adjacency-list trees. Adminix renders the current scoped rows in server-side tree preorder, signs both the rendered primary keys and their parent map, and sends adminix_reorder_parent_ids only for tree mode. Pointer drag reorders rows inside the same parent; keyboard ArrowRight indents a row under the previous sibling, ArrowLeft outdents it one level, and ArrowUp/ArrowDown move it among siblings. Tree reorder controls are hidden when the current scope is an incomplete tree and a visible row's parent is outside the rendered row set, so saving cannot detach hidden parents.

For the built-in SQL/Eloquent writer, tree reorder updates the configured parent field and normalizes sort_order inside each sibling group. Use the third argument when root rows use a sentinel such as 0 instead of NULL: treeReorderable('sort_order', 'parent_id', 0). Use reorderUsing() when your tree uses materialized paths, nested sets, fractional ranks, custom locks, or storage-specific constraints.

Use authorizeReorderUsing() to add a module-level authorization guard:

Use reorderUsing() for MongoDB, external services, custom rank algorithms, application-side locks, version checks, or any storage where the built-in SQL/Eloquent writer should not decide persistence. Adminix still validates the signed rendered row set before calling the handler.

ListReorderRequest exposes:

• module() for the server-side ListModule;

• previousIds() for the signed row order that was rendered;

• orderedIds() for the submitted permutation;

• parentIds() for the submitted tree parent map, empty for flat reorder;

• params() for signed page parameters after Adminix param-index compatibility resolution;

• relationContext() for signed relation child-list context, when present;

• httpRequest() for the original Laravel request.

adminix:doctor warns when reorderable lists miss a primary key field, base order field, valid ascending sorting, or use pagination. For the built-in writer it also checks that the reorder field exists in the SQL datasource, and tree reorder checks the configured parent field.

Column visibility

columnVisibility() adds a Columns section to the compact list settings dropdown for the current ListModule. Only fields marked with hideable() or defaultHidden() are included in that section. When the list uses columnVisibility() or savedTableViews(), the same section also exposes server-declared visible fields for browser-side column order, width, and pinned-side controls. Hidden fields, row reorder handles, row detail toggles, bulk checkboxes, inline edit buttons, and row action service columns are not part of the configurable column layout. The list settings dropdown grows to its content height and only uses vertical scrolling when the menu would exceed the viewport. On narrower desktop viewports, the list settings button shifts left only when its screen position vertically overlaps the fixed shell notification bell. Column toggles, density options, reset, and CSV export actions share the same menu item sizing, spacing, rounded corners, and hover treatment. Column toggles are rendered as switch controls, matching boolean field controls elsewhere in Adminix.

Result: Adminix shows a gear-icon settings button as a root-level absolute control aligned to the list title area. The control does not reserve toolbar or filter space; when a list has no title, it stays inside the list root without adding an empty row. The Customer column is visible by default and can be hidden by the user. The Internal note column is hidden by default and can be shown from the same settings menu. Visible list columns can be moved left/right, assigned an auto, narrow, medium, wide, or full width preference, and pinned left or right. pinnedLeft() and pinnedRight() set the default sticky side; clicking the same pin button in the settings menu unpins the column for that browser or saved view. The hidden id field and service columns for inline edit or row actions are not controlled by column visibility.

Column visibility, column order, column width, and column pinning are browser-side presentation settings. They are stored in local storage by list name and do not change request keys, datasource, criteria, filters, sorting, row actions, authorization, or export scope. When savedTableViews() is enabled, named table view presets can also persist normalized column order, width, and pin state through the configured table view provider. For server-side list visibility, use ListField::hiddenOnIndex()/hideOnIndex(). Hidden-on-index fields are not rendered in the table and are not writable through inline edit. adminix:doctor warns when a hidden/internal or hidden-on-index list field is marked pinned, because it cannot render as a sticky table column.

Table summaries

Use field-level summary helpers when a list needs footer totals aligned with its rendered columns. Adminix computes summary values server-side from the same list query scope used for the visible records: datasource, base criteria, active lens, filters, search, and sorting are applied, but pagination is not.

Result: Adminix renders a <tfoot> row below the list body. The footer uses the same data-adminix-list-column contract as header and body cells, so browser-side column visibility, order, width, reset, saved table views, and pinned columns keep footer cells aligned.

Available helpers:

• sum(?string $label = null);

• avg(?string $label = null)/average(?string $label = null);

• min(?string $label = null);

• max(?string $label = null);

• countSummary(?string $label = null);

• summarize(ListSummaryAggregateEnum|string $aggregate, ?string $label = null);

• summaryLabel(?string $label).

Money fields format sum, avg, min, and max with the configured currency and decimals. countSummary() renders as a plain number even when used on a money field.

Summaries are display-only and do not change list datasource, filters, sorting, export, row actions, authorization, or writable fields. adminix:doctor warns when a summary is configured for a hidden/internal or hidden-on-index field, or when the summary field does not exist in a known SQL/Eloquent datasource table.

Grouped rows

Use groupBy($field, $label = null) when a list needs visual group headers between rows. Adminix groups the already prepared rows for the current rendered page, so datasource, criteria, active lens, filters, search, sorting, pagination, row actions, exports, and writes keep their normal server-side behavior.

Result: Adminix inserts full-width group header rows inside the table body before each contiguous group. The group field must be present in the ListField collection so Adminix can prepare its row value; it may be hidden from the index table when the value should appear only in the group header. groupBy() does not reorder records by itself. Configure sorting() by the same field, or use a lens/default query order, when groups should be contiguous.

Use ungrouped() to clear a previously configured grouping helper in composed module factories. adminix:doctor warns when groupBy() references a field that is not configured in the list or is missing from a known SQL/Eloquent datasource table.

Density and sticky table controls

densitySwitcher(), stickyHeader(), and stickyActions() are opt-in presentation helpers for wide or frequently used tables.

Result: Adminix renders Comfortable and Compact density choices inside the gear-icon list settings menu. The selected density is stored in browser local storage by list name. Compact density reduces table cell padding plus inline row controls such as editable inputs, selects, row action buttons, switches, date-range/key-value editors, async selects, and row images. Inline controls use a 32px minimum height, row images cap at 38px, cells align content vertically in the middle, and action button icons keep the normal UI-kit gap from text. stickyHeader() keeps table headers visible inside the scroll container. stickyActions() keeps the existing final service column visible while the table fits the available width. When a list table is wider than the available viewport, Adminix preserves the table's content width, moves the service column into the horizontal scroll flow, and uses horizontal scrolling instead of compressing or overlapping right-side columns into data cells.

These controls do not create a new action layer. Existing addAction()/addActions() links, non-GET forms, confirm prompts, tooltips, modal togglers, and record:*/param:* route parameters continue to render through the same row action contract. If the list also uses rowActionsDropdown(), stickyActions() keeps the dropdown trigger in the same service column.

CSV export

exportCsv() adds an Export CSV action to the list settings menu for the current ListModule. CSV export is disabled by default and must be enabled per list.

Result: Adminix shows an Export CSV action inside the gear-icon list settings menu. The endpoint applies the same server-side datasource, criteria, active lens, filters, search, and sorting as the list. The current pagination page is ignored, and export rows are capped by the configured limit. The default limit is 10000.

The browser cannot choose a datasource or arbitrary columns for CSV export. Adminix signs the current page params when rendering the export link so param:* criteria use the same route context as the visible list. ListFieldTypeEnum::HIDDEN fields are excluded by default. Use ListField::exportable() only for hidden fields that are safe to include in the CSV. Fields hidden with hiddenOnIndex() are also excluded unless they are explicitly marked exportable(). Row actions, inline edit controls, service columns, and UI-only column visibility are not exported.

Bulk actions

Bulk actions are opt-in server-side actions for selected rows in a ListModule. They render a checkbox column, Select all current page checkbox, action dropdown, selected count, and submit button above the table.

Result: Adminix shows bulk controls above the list. The button stays disabled until the user selects at least one current-page row and one configured action. When confirm() is configured, the browser shows that confirmation before submitting. The web endpoint redirects back with a success or error toast, or returns a direct Response when the handler returns one.

BulkAction settings:

• name() is the stable server-side action key submitted by the browser.

• title() is the dropdown label.

• icon() stores an optional Bootstrap icon class for package consumers and future renderers.

• tooltip() stores optional helper text for package consumers and future renderers.

• color() stores an optional ColorsEnum value or CSS color string.

• destructive() marks dangerous actions for custom renderers and future UI states.

• confirm() sets an optional submit confirmation message.

• criteria() stores optional action visibility criteria metadata; execution still uses the selected row scope.

• addField()/addFields() declare input fields shown before the selected bulk action is submitted.

• handler() accepts a callable, object, or class string. Implement BulkActionHandlerInterface for reusable actions.

• authorizeUsing()/authorization() accepts a boolean, callable, object with authorize(), or class string.

• batchLimit() caps selected scalar IDs before the handler runs. Default is 1000.

• queued('Message') dispatches the handler through Laravel queues after the normal server-side scope and authorization checks.

• progressTrigger() starts a matching ProgressBarModule trigger when the selected action is submitted.

• onConnection() and onQueue() optionally select the Laravel queue transport for queued bulk actions.

• actionMetadata() returns the shared Actions metadata DTO.

BulkActionRequest gives handlers:

• module() and action() from server-side configuration;

• requestedIds() from the request after scalar normalization;

• selectedIds() after applying the current list scope;

• params() after signed page-param context verification and legacy index normalization;

• query() already scoped to selected records;

• primaryKey() from the list module;

• httpRequest() for request/session context when needed.

• fields() and field($name, $default = null) for server-declared action field values.

Action fields are documented in Actions. They are submitted as adminix_action_fields[...], but Adminix only passes keys declared on the selected server-side BulkAction to the handler.

Handlers can return:

• BulkActionResult::success('Message');

• BulkActionResult::error('Message');

• BulkActionResult::validation(['field' => ['Message']]);

• BulkActionResult::redirect('/adminix/orders');

• BulkActionResult::openInNewTab('/adminix/orders/export.csv');

• BulkActionResult::modal('Title', 'Body');

• BulkActionResult::download($response) or a Symfony/Laravel Response for downloadable/custom responses.

Typed action responses are documented in Actions. Queued actions are documented in Actions.

The endpoint resolves page, module, relation context, and action from server-side module configuration. The browser submits only selected IDs and action name. Datasource, primary key, criteria, active lens, filters, search, sorting, relation parent scope, and page params are resolved server-side. IDs outside the current criteria/search/filter/relation scope are ignored; if no selected ID remains in scope, the request fails with a controlled validation error. After a handler returns a normalized result, Adminix dispatches BulkActionExecuted and passes the scope-filtered selected IDs in audit metadata. See Audit for recorder and listener examples.

Bulk actions do not replace row actions. Existing addAction()/addActions() links, non-GET row forms, modal togglers, confirm prompts, tooltips, and record:* params remain the row action contract.

Searching

Determines possibility to make full-text search in source table.

Example:

Filters

Add filters to the top of the module, near to search input. Provides the ability to filter the list by specific fields.

There are several types of filters available:

• ListFilter - AlexKudrya\Adminix\Modules\List\ListFilter

• ListDateFilter - AlexKudrya\Adminix\Modules\List\ListDateFilter

• ListDateRangeFilter - AlexKudrya\Adminix\Modules\List\ListDateRangeFilter

Saved table views

savedTableViews() enables user-owned table view presets for a ListModule. It adds a Saved views section to the list settings menu where the current user can save, apply, and delete named presets.

Saved table views are different from ListLens. ListLens is server-defined PHP configuration. Saved table views are user-created presets stored by a provider.

Adminix stores only normalized table state:

• current list search key, configured quick filter, configured filters, configured lens, and one valid configured sort key;

• browser-only column visibility state for hideable() fields when columnVisibility() is enabled;

• browser-side column order, width, and pin preferences for rendered list fields;

• compact density when densitySwitcher() is enabled.

Pagination is not saved. Applying a saved table view removes the current list page and applies the saved search/quick/filter/lens/sort state to the URL. Unrelated query parameters and other list modules are preserved.

Reset controls

resetControls() adds a Reset view action to the list settings menu for the current ListModule. It is disabled until the current URL or browser storage contains state for that list.

Result: when the URL contains keys such as search-orders, quick-orders, filter-orders-status, sort-orders-created_at, lens-orders, or page, Adminix shows an enabled Reset view action inside the gear-icon list settings menu. The same action is enabled when browser-only view state exists for the list, such as hidden/shown columns, custom column order, custom column widths, custom pinned columns, or compact density. Clicking it returns to the same page without current-list URL state and clears current-list browser view state. Unrelated query parameters and another list module's view state are preserved.

This is a presentation and URL-state convenience only. It does not create a new server-side action endpoint and does not change list filters, row actions, datasource, or authorization behavior.

Mobile behavior

ListModule keeps the same PHP configuration and request contract on mobile. Search, lenses, filters, sorting, pagination, editable rows, row actions, and modal togglers still use the same module name and server-side configuration.

Example configuration:

Result:

• desktop renders filters inline above the table;

• narrow screens show a Filters button with an active-filter count;

• the button opens a drawer containing the same ListFilter, ListDateFilter, and ListDateRangeFilter controls;

• changing a filter still writes the same filter-{moduleName}-{field} query key and resets pagination;

• wide tables scroll horizontally inside the table area, not across the whole Adminix shell;

• row actions remain the existing buttons/forms/modal togglers, including route params, CSRF methods, confirm text, icons, and tooltips.

The mobile drawer is a presentation wrapper only. Do not add browser-owned datasource, action, or filter metadata; continue to configure lists from PHP classes.

Soft-delete row actions

restoreAction() and forceDeleteAction() enable built-in row forms for Eloquent models that use Laravel SoftDeletes. Use softDeleteActions() to enable both actions on the same list.

Result: Adminix renders Restore and Force delete controls only for rows whose source Eloquent model is currently trashed. Active rows do not receive those built-in controls. The forms submit with CSRF and a signed page/module/route-param context to the Adminix soft-delete action endpoint.

Requirements:

• the list dataSource() must be an Eloquent model class using SoftDeletes;

• the list must expose trashed rows through withDeleted() or through at least one ListLens::withDeleted();

• the primary key must be present in the rendered row, usually as a hidden ListField;

• tenant/user boundaries must still be expressed in server-side criteria(), policies, guards, or relation context.

On submit Adminix re-resolves the page, module, relation context, route params, datasource, primary key, criteria, active lens, filters, search, sorting, and current request scope from server-side configuration. It then verifies that the target record is still inside that scope and still trashed() before calling restore() or forceDelete(). Browser-provided datasource, writable fields, primary-key names, deleted state, tenant ids, and param:* values are not trusted.

forceDeleteAction() is irreversible. Use it only for records where permanent deletion is acceptable for your application.

adminix:doctor reports:

• an error when restore/force-delete actions are configured on a non-Eloquent datasource or a model without SoftDeletes;

• a warning when actions are enabled but neither the module nor any lens can expose soft-deleted rows.

Successful restore and force-delete operations dispatch audit events and flash typed Adminix notifications.

Clone actions

cloneAction() enables a built-in per-row clone form. bulkCloneAction($batchLimit = null) adds a built-in adminix_clone bulk action to the existing bulk action pipeline. Use cloneActions() to enable both on the same list.

Result: Adminix renders a Clone row action for rows with the configured primary key and a Clone option in the bulk action dropdown. The row form submits with CSRF and a signed page/module/route-param context. The bulk option uses the normal bulk endpoint, selected IDs, confirmation, batch limit, and scope filtering.

Clone data is derived server-side. By default Adminix copies rendered index ListField columns that exist in the datasource table. It skips the primary key, hidden fields, created_at, updated_at, and deleted_at. It also merges equality values from server-side criteria() after signed page params are resolved, so tenant or parent scope fields such as tenant_id = param:0 can be preserved even when the scope field is hidden.

On submit Adminix re-resolves the page, module, relation context, route params, datasource, primary key, criteria, active lens, filters, search, sorting, and current request scope from server-side configuration. The source record must still be inside the current list scope. The browser cannot choose the datasource, clone fields, writable fields, primary-key names, tenant ids, or param:* values.

Requirements and caveats:

• the list dataSource() must resolve to an Eloquent model table or a plain SQL table;

• at least one rendered index ListField must be backed by a datasource column after skipped fields are removed;

• unique columns, required hidden columns, custom defaults, file paths, and sensitive fields should be modeled intentionally in the consuming app before clone is enabled;

• bulkCloneAction($batchLimit) can lower the default selected-row cap; the default is the normal bulk limit of 1000;

• relation child lists keep their signed relation context and parent scope.

adminix:doctor reports:

• an error when clone actions are configured for a datasource that cannot be resolved to an existing SQL/Eloquent table;

• a warning when clone actions are enabled but no cloneable rendered index field remains.

Successful row and bulk clone operations dispatch resource.cloned audit events and flash typed Adminix notifications. Bulk clone also records the normal bulk.executed audit event with the scope-filtered selected IDs.

Actions

"Actions" is an array of control buttons for every single record, to do some actions, such as "open", "edit", "delete", or wherever else you need.

Example:

To add Action buttons to List module you need paste AlexKudrya\Adminix\Modules\Link\AdminixLinkModule or AlexKudrya\Adminix\Modules\Link\LinkModule class instances as an argument to addAction or addActions method of AdminixPage object.

Action buttons syntax is similar to Link module

By default, Adminix renders row actions inline in the final service column. For dense tables with many row controls, call rowActionsDropdown() on the same ListModule to render one compact vertical three-dots button per row. Clicking it opens a small contextual dropdown next to the trigger and shows the same configured actions inside the menu.

Result: every row keeps a single bi-three-dots-vertical trigger in the action column. The dropdown contains the existing GET links, POST/PUT/PATCH/DELETE forms with CSRF and confirm prompts, and modal togglers. If an action has an icon but no title, the dropdown uses the action name() as a text label so the menu remains readable. Rows where criteria() hides all actions still render an empty service cell to keep the table columns aligned.

rowActionsDropdown() is presentation-only. It does not change action authorization, criteria evaluation, route parameter substitution, signed modal relation context, request payloads, datasource, or persistence behavior.

New item link

Usually, in the admin panels, lists have the ability to add new records, and the New resource module is used for this. In order to display a link to a page with such a module in the correct place in the "list" module, there is this directive

Format is similar to Link module or Actions

Example:

or

Appearance examples

Here is example of List without editable mode:

Here is example of List with editable mode: