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.

A $ path is the exception: data-list="$store.path", data-list="$query.rows", or data-query="name" inside a row names a shared source, so every row renders the same array and follows it. A per-row dropdown fed from one options store is the typical use.

// ✅ 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. The computed receives the current habit
        // as its argument when it evaluates inside the outer data-list.
        last7Days(habit) {
            // ... derive 7 cells from habit.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] is undefined; a raw field of the same name shadows the computed. If your row already has a reactions field and you also want a derived view, name the computed differently (reactionChips) so the data-list can find it.
path is 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 needed

Dynamic 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 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

Mini Todo List

Filtering, item actions, and computed counts over one data-list.

Demo Code

Previous Advanced Lists

Next Why Pools?