List Patterns & Reference
Performance optimization, context variables, style binding, and array mutation patterns for lists.
Prerequisites: For list basics see Lists & Iteration. For filtering and external data, see Advanced Lists.
List Performance Optimization
Automatic Optimizations:
- Only changed list items are re-rendered
- Templates are cloned efficiently using DocumentFragment
- Automatic element recycling for large lists
- Computed properties are cached across list items
Large List Best Practices
For very large lists (1000+ items), consider these patterns:
// Pagination pattern
computed: {
paginatedItems() {
const start = (this.currentPage - 1) * this.pageSize
const end = start + this.pageSize
return this.allItems.slice(start, end)
}
}
// Virtual scrolling for extremely large lists
computed: {
visibleItems() {
const startIndex = Math.floor(this.scrollTop / this.itemHeight)
const endIndex = startIndex + this.visibleCount
return this.allItems.slice(startIndex, endIndex)
}
}List Context and Data Access
Understanding data access patterns within list templates:
| Context | Syntax | Description |
|---|---|---|
| Item Property | data-bind="propertyName" |
Direct access to current item's properties |
| Component State | data-bind="state.componentProperty" |
Access component's state properties |
| Component Computed | data-bind="propertyName" |
Access component's computed properties |
| Item Computed | data-bind="propName" |
Computed properties scoped to current item |
List Context Variables
WildflowerJS provides special variables within list templates that give you information about each item's position. These are particularly useful for conditional styling with data-bind-class:
| Variable | Type | Description |
|---|---|---|
_index |
Number | Zero-based index of the current item (0, 1, 2, ...) |
_length |
Number | Total number of items in the list |
_first |
Boolean | true if this is the first item in the list |
_last |
Boolean | true if this is the last item in the list |
Usage Examples
Use list context variables in data-bind-class expressions to create position-aware styling:
<!-- Disable up/down buttons at list boundaries -->
<!-- Also disable both buttons when there's only one item -->
<div data-list="items">
<template>
<div class="item">
<button data-action="moveUp"
data-bind-class="_first || _length === 1 ? 'btn-secondary disabled' : 'btn-primary'">
↑
</button>
<span data-bind="name"></span>
<button data-action="moveDown"
data-bind-class="_last || _length === 1 ? 'btn-secondary disabled' : 'btn-primary'">
↓
</button>
</div>
</template>
</div>
<!-- Style based on position -->
<div data-list="items">
<template>
<div data-bind-class="_index === 0 ? 'highlight-first' : _last ? 'highlight-last' : ''">
<span data-bind="name"></span>
</div>
</template>
</div>
<!-- Show different message based on list size -->
<div data-list="items">
<template>
<div data-bind-class="_length < 3 ? 'compact-view' : 'full-view'">
Item <span data-bind="_index + 1"></span> of <span data-bind="_length"></span>
</div>
</template>
</div>
Tip: When a list has only one item, that item is both
_first and _last. For move buttons, you may want to also check _length === 1 to disable both buttons when there's nothing to move.
Action Handler Context (details object)
In action handlers, the details parameter provides the same context information plus direct access to the item and list data:
| Property | Type | Description |
|---|---|---|
details.index |
Number | Zero-based index of the current item |
details.item |
Object | The actual data object for this list item |
details.list |
Array | The full array being rendered |
details.length |
Number | Total number of items in the list |
details.first |
Boolean | true if this is the first item |
details.last |
Boolean | true if this is the last item |
details.parent |
Object | Parent list context (for nested lists) |
// Using details in action handlers
moveUp(event, element, details) {
if (details.first) return // Already at top
const { index, item } = details
this.items.splice(index, 1)
this.items.splice(index - 1, 0, item)
},
moveDown(event, element, details) {
if (details.last) return // Already at bottom
const { index, item } = details
this.items.splice(index, 1)
this.items.splice(index + 1, 0, item)
},
removeItem(event, element, details) {
const { index, item } = details
if (confirm(`Delete "${item.name}"?`)) {
this.items.splice(index, 1)
}
}Nested List Actions with Parent Context
When working with nested lists (like a kanban board with columns containing cards), action handlers in the inner list receive details.parent which provides access to the parent list's context. This is essential for operations that need to know which parent container an item belongs to.
<!-- Kanban-style nested list structure -->
<div data-component="kanban-board">
<div class="board" data-list="columns">
<template>
<div class="column">
<h3 data-bind="name"></h3>
<div data-list="cards">
<template>
<div class="card">
<span data-bind="title"></span>
<button data-action="deleteCard">Delete</button>
<button data-action="moveCard">Move</button>
</div>
</template>
</div>
</div>
</template>
</div>
</div>wildflower.component('kanban-board', {
state: {
columns: [
{ id: 'todo', name: 'To Do', cards: [{ id: 'c1', title: 'Task 1' }] },
{ id: 'done', name: 'Done', cards: [{ id: 'c2', title: 'Task 2' }] }
]
},
deleteCard(event, element, details) {
// details.item = the card that was clicked
// details.index = index of the card in its column's cards array
// details.parent.item = the column containing the card
// details.parent.index = index of the column in columns array
const { item, parent } = details;
const columnIndex = parent.index;
// Remove the card from the correct column
this.columns[columnIndex].cards =
this.columns[columnIndex].cards.filter(c => c.id !== item.id);
console.log(`Deleted "${item.title}" from column "${parent.item.name}"`);
},
moveCard(event, element, details) {
const card = details.item;
const sourceColumn = details.parent.item;
const sourceColumnIndex = details.parent.index;
// Now you have everything needed to move the card to another column
// ...
}
});
Triple-nested lists: For 3+ levels of nesting, access grandparent via
details.parent.parent:
// companies → departments → employees
const employee = details.item; // { name: 'Alice' }
const department = details.parent.item; // { name: 'Engineering' }
const company = details.parent.parent.item; // { name: 'TechCorp' }Nested data-list Source Resolution
Inside a row template, data-list reads item[path] first (fast path for raw fields) and falls back to evaluating an item-level computed of the same name when the field is undefined. This mirrors how data-bind, data-bind-class, and data-show already resolved item-level computeds, so the same authoring pattern works at every binding site, including nested-list sources.
// ✅ Item-level computed used directly as the inner data-list source
wildflower.component('habit-tracker', {
state: {
habits: [
{ id: 'h1', name: 'Read', completions: { /* ... */ } },
{ id: 'h2', name: 'Walk', completions: { /* ... */ } }
]
},
computed: {
// Per-habit 7-day grid. `this.completions` is the current habit's
// raw map when this evaluates inside the outer data-list template.
last7Days() {
if (this.id === undefined) return []
// ... derive 7 cells from this.completions
return /* [{ id, day, done }, ...] */
}
}
})<div data-list="habits" data-key="id">
<template>
<div class="habit">
<span data-bind="name"></span>
<!-- last7Days isn't a raw field on the habit row;
the framework evaluates the computed per-row instead -->
<div class="grid" data-list="last7Days" data-key="id">
<template><span data-bind-class="cellClass"></span></template>
</div>
</div>
</template>
</div>
Caveats. The fallback only fires when:
item[path]isundefined; a raw field of the same name shadows the computed. If your row already has areactionsfield and you also want a derived view, name the computed differently (reactionChips) so the data-list can find it.pathis a flat name with no dots; dotted paths (a.b.c) skip the fallback. For traversal lookups, define a flat-named computed.
The enrich-at-parent pattern (build the array once in a parent-level computed and attach it to each item before rendering) is still valid and sometimes preferable: it makes the rendered row shape obvious in DevTools, and it groups the derivation alongside the row mapping. Use it when the per-row array is shared across multiple bindings, or when DevTools-inspectable item shape matters more than terse component code:
// Still useful: enrich rows at the parent level when you want the array
// visible on the row data itself.
wildflower.component('habit-tracker', {
computed: {
habitsWithGrid() {
return this.habits.map(h => ({
...h,
last7Days: this._buildLast7Days(h)
}))
}
}
})
// <div data-list="habitsWithGrid"><template>
// <div data-list="last7Days">... ← reads habit.last7Days raw, no fallback neededDynamic Style Binding in Lists
To apply per-item styles in lists (e.g., different background colors for each column), use item-level computed properties that return style objects:
wildflower.component('styled-board', {
state: {
columns: [
{ id: 'todo', name: 'To Do', color: '#fff3e0', cards: [...] },
{ id: 'progress', name: 'In Progress', color: '#e3f2fd', cards: [...] },
{ id: 'done', name: 'Done', color: '#e8f5e9', cards: [...] }
]
},
computed: {
// Item-level computed (has parameter) - returns style OBJECT
columnStyle(item) {
return {
backgroundColor: item.color || '#f5f5f5',
borderColor: item.color
};
},
// Works in nested lists too - receives the nested item
cardStyle(item) {
const priorityColors = {
high: '#ffebee',
medium: '#fff8e1',
low: '#e8f5e9'
};
return {
backgroundColor: priorityColors[item.priority] || '#ffffff'
};
}
}
});<div data-list="columns">
<template>
<!-- computed:columnStyle receives column item, returns {backgroundColor: '...'} -->
<div class="column" data-bind-style="columnStyle">
<h3 data-bind="name"></h3>
<div data-list="cards">
<template>
<!-- computed:cardStyle receives card item -->
<div class="card" data-bind-style="cardStyle">
<span data-bind="title"></span>
</div>
</template>
</div>
</div>
</template>
</div>
CRITICAL - Style Binding Syntax:
data-bind-style="styleFn"- Computed returns object like{backgroundColor: 'red', color: 'white'}data-bind-style="styleObject"- Direct path to a style object in state- NOT
data-bind-style="backgroundColor:colorProp"- This syntax is INVALID
Key Pattern: The computed function receives the list item as its first parameter. This works at any nesting level - the framework automatically passes the correct item for that template context.
Array Mutation Methods
WildflowerJS supports direct array mutation - changes are automatically detected and the DOM is updated efficiently:
| Method | Description | Example |
|---|---|---|
push() |
Add items to the end of the array | this.items.push(newItem) |
pop() |
Remove the last item | this.items.pop() |
shift() |
Remove the first item | this.items.shift() |
unshift() |
Add items to the beginning | this.items.unshift(newItem) |
splice() |
Insert, remove, or replace items | this.items.splice(index, 1) |
sort() |
Sort the array in place | this.items.sort((a, b) => a.name.localeCompare(b.name)) |
reverse() |
Reverse the array order | this.items.reverse() |
| Direct assignment | Replace the entire array | this.items = [...filtered] |
Efficient List Operations
The framework intelligently detects the type of array operation and optimizes DOM updates:
// Adding items - only new DOM elements are created
this.items.push({ id: 1, name: 'New Item' })
// Removing items - only affected elements are removed
this.items.splice(index, 1)
// Reordering - efficient swap detection
const item = this.items[index]
this.items.splice(index, 1)
this.items.splice(newIndex, 0, item)
// Batch operations - combine multiple mutations efficiently
this.items.push(item1, item2, item3)
// Full replacement - smart diffing determines minimal changes
this.items = this.items.filter(item => item.active)
Automatic Optimization: The framework detects append operations (adding to the end) and only creates new DOM elements for the added items. Similarly, removal operations only affect the specific removed elements, not the entire list.
List Best Practices
Do
- Use computed properties for filtering/sorting
- Provide unique keys for list items when possible
- Keep list item templates lightweight
- Use pagination for very large datasets
- Leverage the framework's automatic indexing
Don't
- Mutate arrays directly without framework knowledge
- Create complex logic in template bindings
- Render thousands of items without pagination
- Use splice() unnecessarily for simple updates
- Forget to handle empty list states