GitHub v1.3.1

listStrategy

Stable

Decides whether an observed array change triggers a normal reactive update or a direct DOM patch for the two patterns that can be applied in place.

Browser only.

The strategy applies to observers that run in the browser. It has no effect during SSR, where every list is rendered from scratch.

Signature

typescript
Code copied!
export const listStrategy:
  | 'full'
  | 'minimal'
  | {
      mode: 'full' | 'minimal'
      key?: (item: any) => any
    }

'full' is the default. The observed value is handed to the observer and the component updates through normal reactivity.

'minimal' inspects the old and new arrays first. When the change is a two-item swap or a single removal, Coralite patches the DOM container directly and skips the observer callback for that change. Anything else falls back to the full path.

Key extraction

Pattern detection compares items by key. The key function wins; without one, Coralite uses item.id, then item.key, then strict identity. Objects without either property can only be matched by reference.

javascript
Code copied!
export const listStrategy = {
  mode: 'minimal',
  key: (row) => row.uuid
}

Precedence

The first value found wins:

  1. The component's listStrategy export.
  2. The legacy reconcile and key exports, combined into one strategy.
  3. config.listStrategy on the global configuration.
  4. The CORALITE_LIST_STRATEGY environment variable.
  5. 'full'.

Use the component export when only one list benefits. Use the config when a whole site renders large tables and the same trade-off applies everywhere.

Container resolution

For a patch, Coralite needs the element whose children are the rows. It looks for a ref matching the observed key, then tbody, list and container refs, then the first tbody, ul, ol or [ref] in the component, and finally the first child element.

Name the ref when the container is not obvious. A patch applied to the wrong element is worse than a full re-render:

html
Code copied!
<template id="data-table">
  <table>
    <tbody ref="rows"></tbody>
  </table>
</template>

<script type="module">
  export const listStrategy = {
    mode: 'minimal',
    key: (row) => row.id
  }
</script>

When minimal pays off

minimal avoids re-rendering rows that did not change, which matters for long tables where a swap would otherwise rebuild every cell. For short lists the difference is noise, and the full path is simpler to reason about.

The strategy only covers swaps and single removals. Appends, multiple removals and arbitrary reorderings still take the full path, so do not treat it as a general virtual DOM.

Diagnostics

  • CORALITE-E107 reports a literal mode other than 'full' or 'minimal'. A malformed object fails registration before validation runs.