Skip to main content

List Users Block

ListUsers is a user directory table built on MUI Table primitives. It supports status filtering tabs, dismissible search chip filters, status change dropdown actions, pagination, and direct layout customization through compound children or block overrides.

Installation​

npm install @nodeblocks/frontend-list-users-block

What You Need​

ItemWhy it matters
listUsersTitleHeading text or React Node for the table section
dataArray of user records matching ListUsersRowData (id, name, createdAt, status)
labelsText labels object mapping headers, search placeholders, row actions, and empty states
Presentational component

ListUsers does not maintain list state. Manage parameters like current page, active search values, search chips, and tab filters in your application state and handle them in callback events.

Code Examples​

Live Editor
function Example() {
  const [page, setPage] = React.useState(1);

  const users = [
    {
      id: '1',
      name: 'John Smith',
      createdAt: '2026-01-15T10:30:00Z',
      status: 'active'
    },
    {
      id: '2',
      name: 'Sarah Johnson',
      createdAt: '2026-01-14T09:15:00Z',
      status: 'inactive'
    }
  ];

  const labels = {
    emptyStateMessage: 'No users found',
    searchFieldPlaceholder: 'Search users...',
    headerRow: {
      name: 'Name',
      createdAt: 'Created At',
      status: 'Status',
    },
    cellData: {
      statusActive: 'Active',
      statusInactive: 'Inactive',
    },
  };
  const [lastAction, setLastAction] = React.useState('Navigation feedback will appear here.');

  return (
    <div style={{ minHeight: 400 }}>
      {/** Inline feedback for navigation */}
      <ListUsers
        listUsersTitle="User Directory"
        labels={labels}
        data={users}
        onNavigate={(to) => setLastAction(`Navigating: ${to}`)}
        rowHref={(row) => `#users/${row.id}`}
        pagination={{
          currentPage: page,
          totalPages: 1,
          onPageChange: setPage,
        }}
      />
      <div style={{marginTop: 12, color: '#475569', fontSize: 13}}>{lastAction}</div>
    </div>
  );
}
Result
Loading...

Important Props​

Core Props​

PropTypeRequiredDefaultDescription
dataListUsersRowData[]Yes-Array of user record objects
isLoadingbooleanNoundefinedRenders the circular loader instead of default content area when true
onNavigate(to: string) => voidNoundefinedNavigation callback triggered on click actions (such as row clicks)
onItemActivate(rowId: string) => voidNoundefinedCallback triggered when selecting the "Activate" action dropdown option
onItemDeactivate(rowId: string) => voidNoundefinedCallback triggered when selecting the "Deactivate" action dropdown option
resolveRowAction(row: ListUsersRowData) => ('activate' | 'deactivate')[] | undefinedNoundefinedDirect check evaluating active account options per row
shouldShowDropdownMenu(row: ListUsersRowData) => booleanNoundefinedCheck deciding whether to show action dropdown buttons entirely
statusMatch{ inUse: string; notInUse: string }No{ inUse: 'active', notInUse: 'inactive' }Maps raw row.status values to active/inactive text in the generated status column
paginationPaginationPropsNoundefinedStateful pagination controls: { currentPage, totalPages, onPageChange, className? }

Content Props​

PropTypeRequiredDefaultDescription
listUsersTitleReactNodeYes-Heading text or component rendered inside the Title sub-block
labels{ emptyStateMessage: string; searchFieldPlaceholder: string; rowActions?: { activate: string; deactivate: string }; headerRow: { createdAt: string; name: string; status: string }; cellData: { statusActive: string; statusInactive: string } }Yes-Direct layout translation and wording mappings
rowHref(row: ListUsersRowData) => stringNoundefinedDirect row href URL generator callback
tabs{ key: string; label: string; isDisabled?: boolean; subtitle?: string }[]NoundefinedTab filter category items
currentTabstringNoundefinedCurrently selected tab identifier
onTabChange(tab: string) => voidNoundefinedCallback triggered on category tab clicks
searchValuestringNoundefinedValue of search text input
onSearchFieldChange(value: string) => voidNoundefinedCallback triggered when typing into search text input
onSearchSubmit() => voidNoundefinedTriggered on search button clicks or Enter submits
searchChipsTitleReactNodeNoundefinedLabel displayed next to active chip filter badges
searchChipsBaseTableSearchChip[]NoundefinedFilters mapped inside the dismissible search chips bar
onSearchChipDelete(chip: BaseTableSearchChip, index: number, event: SyntheticEvent) => voidNoundefinedCallback triggered on active chip dismissals

labels Structure​

Provide exact wording keys inside the labels object matching this layout structure:

{
  emptyStateMessage: string;
  searchFieldPlaceholder: string;
  rowActions?: {
    activate: string;
    deactivate: string;
  };
  headerRow: {
    createdAt: string;
    name: string;
    status: string;
  };
  cellData: {
    statusActive: string;
    statusInactive: string;
  };
}

Layout and Composition Props​

PropTypeRequiredDefaultDescription
childrenBlocksOverride | ReactNodeNoundefinedCompound child elements or override function child
classNamestringNoundefinedStyling class applied on the outer container
sxSxPropsNoundefinedMUI SX styling overrides passed to the outer Stack

ListUsers inherits all StackProps (except children). Default block order is ['header', 'searchChips', 'content', 'pagination'] (defaultBlockOrder).

Default UI Blocks​

BlockBuilt onNotes
ListUsers (root)BaseTableDirect table wrapper establishing theme contexts
ListUsers.HeaderBaseTable.HeaderFlex container holding Title and search Actions
ListUsers.TitleBaseTable.Header.TitleRenders the main head text
ListUsers.ActionBaseTable.Header.ActionsWraps user search input components
ListUsers.SearchChipsBaseTable.SearchChipsContainer holding active search filters
ListUsers.TabsBaseTable.TabsAvailable for compound/override layouts; reads tab definitions from root tabs
ListUsers.ContentBaseTable.ContentContainer block holding loaders or tabular data grids
ListUsers.LoaderBaseTable.Content.LoaderProgress spinner shown during loadings
ListUsers.TableBaseTable.Content.GridPresents user name, creation date, status cells, and actions
ListUsers.PaginationBaseTable.PaginationStandard pagination controls mapped at bottom

TypeScript​

import { ListUsers } from '@nodeblocks/frontend-list-users-block';
import type { ListUsersRowData } from '@nodeblocks/frontend-list-users-block';

const users: ListUsersRowData[] = [
  {
    id: 'usr_001',
    name: 'Kenji Sato',
    createdAt: '2026-05-27T01:00:00Z',
    status: 'active',
  }
];

const labels = {
  emptyStateMessage: 'No employees found',
  searchFieldPlaceholder: 'Search database',
  rowActions: { activate: 'Enable', deactivate: 'Suspend' },
  headerRow: {
    name: 'Member',
    createdAt: 'Joined',
    status: 'Status',
  },
  cellData: { statusActive: 'Active', statusInactive: 'Suspended' },
};

<ListUsers
  listUsersTitle="Corporate Registry"
  labels={labels}
  data={users}
/>;