Page:
ui list HowTo
Pages
Home
ai Overview
ai gemini Overview
api HowTo
api Overview
api client HowTo
api client Overview
api server HowTo
api server Overview
api server express HowTo
app HowTo
app Overview
auth HowTo
auth Overview
auth basic HowTo
auth basic Overview
auth firebase HowTo
auth firebase Overview
auth oidc Overview
auth pocketbase HowTo
auth pocketbase Overview
auth supabase HowTo
auth supabase Overview
backend HowTo
backend Overview
backend firestore Overview
backend migrations Overview
backend postgres Overview
backend restapi Overview
backend restapi recipes Overview
backend sqlite HowTo
backend sqlite Overview
cache Overview
cache redis Overview
cloudwrapper HowTo
cloudwrapper Overview
cloudwrapper firebase HowTo
cloudwrapper firebase Overview
cloudwrapper supabase HowTo
cloudwrapper supabase Overview
code Overview
code github Overview
core HowTo
core Overview
core cli HowTo
core cli Overview
gateway upstream express HowTo
gateway upstream express Overview
i18n HowTo
i18n Overview
i18n en HowTo
i18n en Overview
i18n fr HowTo
i18n fr Overview
log HowTo
log Overview
messaging HowTo
messaging Overview
messaging firebase HowTo
messaging firebase Overview
queue HowTo
queue Overview
queue amqp HowTo
queue amqp Overview
queue aws HowTo
queue aws Overview
queue gcp HowTo
queue gcp Overview
storage HowTo
storage Overview
storage firebase HowTo
storage firebase Overview
storage local Overview
storage s3 HowTo
storage s3 Overview
storage supabase HowTo
storage supabase Overview
studio Overview
testing Overview
types HowTo
types Overview
ui Overview
ui form react Overview
ui list HowTo
ui list Overview
ui list react HowTo
ui list react Overview
worker HowTo
worker Overview
No results
1
ui list HowTo
GitHub Action edited this page 2026-05-21 19:42:21 +00:00
HOWTO - Using @quatrain/ui-list
This document presents simple, medium, and complex usage scenarios of the headless, framework-agnostic @quatrain/ui-list package.
1. Simple Usage: Automatic Model-Driven Collection Mapping
If you have a Quatrain model schema (with PROPS_DEFINITION or properties), the manager can automatically infer columns, pagination limits, and query targets.
import { CoreListManager } from '@quatrain/ui-list'
import { User } from '@quatrain/core' // your Quatrain core model
import { myApiClient } from './apiClient'
// 1. Instantiate the manager using just the Quatrain model schema
const manager = new CoreListManager({
modelSchema: User,
apiClient: myApiClient,
initialPageSize: 10
})
// 2. Subscribe to the reactive state
const unsubscribe = manager.subscribe((state) => {
console.log('Status:', state.status)
console.log('Total count:', state.meta.count)
console.log('Items:', state.items)
})
// 3. Initialize and execute the query
await manager.init()
// Clean up listener when no longer needed
unsubscribe()
2. Medium Usage: Exposer Class Decorator Pattern (@CoreList)
Exposer classes represent list/table controller models in a domain-driven structure. Use the @CoreList class decorator to link metadata schemas and pre-fetch multilingual relationship labels (e.g. translating target references).
Define the Exposer Class
import { CoreList } from '@quatrain/ui-list'
import { Company } from '@quatrain/core'
@CoreList({
endpoint: 'companies',
modelSchema: Company,
defaultSorting: { field: 'name', order: 'asc' },
pagesize: 25,
columns: {
name: {
label: { fr: 'Nom de Société', en: 'Company Name' },
sortable: true
},
email: {
label: 'Email',
sortable: false
},
createdAt: {
label: 'Créé le',
sortable: true
}
}
})
export class CompanyListExposer {
// Write custom domain logic or filters here
}
Consume the Decorated Exposer
import { CoreListManager } from '@quatrain/ui-list'
import { CompanyListExposer } from './CompanyListExposer'
import { myApiClient } from './apiClient'
const manager = new CoreListManager({
listClass: CompanyListExposer,
apiClient: myApiClient
})
// Initialize the list manager (pre-fetches relations like status lists and executes query)
await manager.init()
// Navigate, paginate, sort, or filter the collection dynamically
manager.setPage(2)
manager.setSorting({ field: 'createdAt', order: 'desc' })
manager.setFilters({ status: 'active' })
3. Complex Usage: Custom Queries & Custom Fetch Function Overrides
For advanced needs, such as integrating compound search strings, handling non-standard query structures, or fetching data through nested RPC operations, override the querying channel using fetchFunction.
import { CoreListManager, ListState } from '@quatrain/ui-list'
import { Project } from '@quatrain/core'
// Imagine we need a list displaying projects, but it requires a custom payload
const manager = new CoreListManager({
modelSchema: Project,
initialPage: 1,
initialPageSize: 50,
initialSorting: { field: 'priority', order: 'desc' },
// Custom fetch override replacing direct REST calls
fetchFunction: async (params: {
offset: number
batch: number
q: Record<string, any>
fsort?: string
osort?: 'asc' | 'desc'
}) => {
// Translate state queries to custom back-end RPC commands
const advancedPayload = {
pagination: {
skip: params.offset,
limit: params.batch
},
sortRules: params.fsort ? [{ column: params.fsort, direction: params.osort }] : [],
searchQuery: params.q.q || '',
statusFilter: params.q.status || 'all'
}
// Execute fetch via custom client
const response = await fetch('/api/rpc/projects/list-active', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(advancedPayload)
})
if (!response.ok) {
throw new Error(`RPC query failed: ${response.statusText}`)
}
const payload = await response.json()
// Return standard Quatrain items & meta shape
return {
items: payload.records, // array of items
meta: {
count: payload.totalCount, // absolute total for pagination
activeCount: payload.activeCount
}
}
}
})
// Reacting to query progress
manager.subscribe((state: ListState) => {
if (state.status === 'loading') {
console.log('Querying RPC service...')
} else if (state.status === 'error') {
console.error('Failed to load projects:', state.error)
} else {
console.log(`Loaded ${state.items.length}/${state.meta.count} projects.`)
}
})
// Trigger query
await manager.init()
// Apply compound search terms that get processed by your custom fetcher
manager.setFilters({ q: 'Search query', status: 'pending' })
Core Documentation
Foundations
Storage, Data & Cache
- backend
- backend-firestore
- backend-postgres
- backend-sqlite
- backend-migrations
- storage
- storage-firebase
- storage-s3
- storage-supabase
- storage-local
- cache
- cache-redis
Queue & Messaging
Auth & Cloud
- auth
- auth-firebase
- auth-supabase
- auth-oidc
- auth-pocketbase
- cloudwrapper
- cloudwrapper-firebase
- cloudwrapper-supabase