ListModal

A full-screen modal that renders a DynamicList with built-in pagination, search, and header action support. It can fetch data from an API (listPath) or accept a static data array. When canCreate is enabled, a floating action button opens a nested FormModal. Header actions support importMany, importOne, and exportMany action types that open their respective nested modals.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | isOpen | boolean | Yes | — | Controls whether the modal is visible. | | onClose | () => void | Yes | — | Called when the modal closes. | | title | string | Yes | — | Title displayed in the modal header. | | backdropStyle | React.CSSProperties | No | — | Inline styles for the modal backdrop. | | windowStyle | React.CSSProperties | No | — | Inline styles merged into the modal window. | | closeButtonStyle | React.CSSProperties | No | — | Styles for the close button. | | closeIcon | string | No | — | Icon name for the close button. | | closeIconPaths | any[] | No | — | Custom icon paths for the close button. | | closeIconSize | number | No | — | Icon size for the close button. | | zIndex | number | No | — | CSS z-index of the modal overlay. | | id | string | No | — | HTML id for the modal element. | | subtitle | string | No | — | Subtitle displayed in the modal header. | | fullScreen | boolean | No | true | When true, the modal occupies the full viewport. | | itemStyle | React.CSSProperties | No | — | Inline styles for each list item. | | startSlots | Slot[] | No | [] | Slots rendered at the start of each list item. | | endSlots | Slot[] | No | [] | Slots rendered at the end of each list item. | | data | any[] \| null | No | null | Static data array. When provided, skips API fetch. | | apiBaseUrl | string | No | — | Base URL for the HTTP client. | | useAuthToken | boolean | No | true | When true, uses the authenticated HTTP client. | | listPath | string | No | — | API path to fetch the list data from. | | reorderPath | string | No | — | API path for item reordering (reserved). | | displayMode | 'row' \| 'grid' | No | — | Layout mode for the list items. | | noContentText | string | No | 'No content available' | Text shown when the list is empty. | | noContentIcon | string | No | 'records' | Icon shown when the list is empty. | | forceRefresh | boolean | No | — | When toggled, forces a list reload. | | isSortable | boolean | No | — | When true, enables drag-to-sort on list items. | | isItemClickable | boolean | No | false | When true, list items are clickable. | | canCreate | boolean | No | false | When true, shows a floating add button that opens a create form. | | createFormConfig | { title?: string; fields: any[]; useAuthToken?: boolean; savePath?: string; zIndex?: number } | No | — | Configuration for the nested create FormModal. Required when canCreate is true. | | showSearchBar | boolean | No | — | When true, displays a search bar in the header. | | searchBarConfig | any | No | — | Configuration object for the search bar. | | headerActions | HeaderAction[] | No | — | Primary action buttons rendered in the header. | | moreHeaderActions | HeaderAction[] | No | — | Secondary actions in the header overflow menu. Supports exportMany, importMany, and importOne action types. | | renderItem | (item: any, index: number) => React.ReactNode | No | — | Custom renderer for each list item. | | onActionClick | (actionData: any, itemData: any) => void | No | — | Called when a slot action is clicked on a list item. | | onItemChangeSuccess | (item: any, message?: string) => void | No | — | Called after a list item change succeeds. Triggers a list reload. | | onItemChangeError | (item: any, error: any) => void | No | — | Called after a list item change fails. | | onItemClick | (item: any, index: number) => void | No | — | Called when a list item is clicked (requires isItemClickable). | | onSlotClick | (slot: Slot, item: any) => void | No | — | Called when a slot element is clicked on a list item. |

Usage

Basic

import React from 'react';
import ListModal from '@/components/modals/ListModal';

export default function Example() {
  const [open, setOpen] = React.useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>View Products</button>
      <ListModal
        isOpen={open}
        onClose={() => setOpen(false)}
        title="Products"
        apiBaseUrl="https://api.example.com"
        listPath="/v1/products"
        useAuthToken
        startSlots={[{ type: 'text', name: 'name', label: 'Name', config: {} }]}
        canCreate
        createFormConfig={{
          title: 'New Product',
          fields: [
            { type: 'text', name: 'name', label: 'Name' },
          ],
          savePath: '/v1/products',
          useAuthToken: true,
        }}
      />
    </>
  );
}