Configurable Component Templates All

Allow parent components to define how child components render their data, enabling flexible and reusable component patterns.

Inversion of Control: Configurable Component Templates let the parent define how data renders while the child provides what data to render. This enables highly reusable components without hardcoding presentation or passing complex render functions. Compare to Vue's Scoped Slots or React's Render Props.

The Concept

Sometimes you want a reusable component where the child provides the data but the parent controls the presentation. Traditional approaches require either:

Hardcoding templates inside the child component (inflexible)
Passing complex render functions or HTML strings (messy)
Using slots, which project content but can't access child data

Configurable Component Templates solve this by letting parents define named templates that children can reference when rendering their data.

Basic Usage: Single Object Binding

The simplest case binds a template to a single object in state using data-with:

data-item-template="name" - Parent defines a named template
data-use-template="name" - Child references the parent's template
data-with="path" - Binds the template to a specific state path

                        <!-- Parent defines HOW user info should look -->
<div data-component="user-page">

    <!-- Define a named template for user display -->
    <template data-item-template="userBadge">
        <div class="card">
            <div class="card-body d-flex align-items-center">
                <div class="rounded-circle bg-primary text-white d-flex align-items-center justify-content-center me-3"
                     style="width: 50px; height: 50px; font-weight: bold; font-size: 1.2rem;">
                    <span data-bind="initials"></span>
                </div>
                <div>
                    <h5 class="mb-0"><span data-bind="name"></span></h5>
                    <small class="text-muted"><span data-bind="title"></span></small>
                </div>
            </div>
        </div>
    </template>

    <!-- Child uses the template with its own data -->
    <div data-component="profile-card">
        <div data-use-template="userBadge" data-with="user"></div>
    </div>
</div>
                    

                        // Parent provides structure and template
wildflower.component('user-page', {
    state: {}
})

// Child provides the data
wildflower.component('profile-card', {
    state: {
        user: {
            name: 'Alice Chen',
            title: 'Engineering Lead',
            initials: 'AC'
        }
    }
})
                    

Live Preview

Reactive Updates

Templates bound with data-with are fully reactive. When the bound data changes, the template automatically updates:

                        <div data-component="status-display">
    <template data-item-template="statusCard">
        <div class="alert" data-bind-class="healthy ? 'alert-success' : 'alert-danger'">
            <strong data-bind="name"></strong>:
            <span data-bind="healthy ? 'Online' : 'Offline'"></span>
            <small class="float-end">Latency: <span data-bind="latency"></span>ms</small>
        </div>
    </template>

    <div data-component="server-monitor">
        <div data-use-template="statusCard" data-with="server"></div>
        <button class="btn btn-primary btn-sm" data-action="toggleStatus">
            Toggle Status
        </button>
        <button class="btn btn-secondary btn-sm" data-action="randomLatency">
            Update Latency
        </button>
    </div>
</div>
                    

                        wildflower.component('status-display', {
    state: {}
})

wildflower.component('server-monitor', {
    state: {
        server: {
            name: 'API Gateway',
            healthy: true,
            latency: 42
        }
    },

    toggleStatus() {
        this.server.healthy = !this.server.healthy
    },

    randomLatency() {
        this.server.latency = Math.floor(Math.random() * 200)
    }
})
                    

Live Preview

Actions in Templates

Actions defined in parent templates bind to the child component's methods. This makes sense because the child owns the data context:

                        <div data-component="product-page">
    <!-- Parent defines template with actions -->
    <template data-item-template="productCard">
        <div class="card">
            <div class="card-body">
                <h5 class="card-title" data-bind="name"></h5>
                <p class="card-text text-muted" data-bind="description"></p>
                <div class="d-flex justify-content-between align-items-center">
                    <span class="h4 mb-0">$<span data-bind="price"></span></span>
                    <!-- Action calls child's method -->
                    <button class="btn btn-primary" data-action="addToCart">
                        Add to Cart
                    </button>
                </div>
            </div>
        </div>
    </template>

    <div data-component="product-display">
        <div data-use-template="productCard" data-with="product"></div>
        <div class="alert alert-info mt-3" data-show="addedToCart">
            Added to cart!
        </div>
    </div>
</div>
                    

                        wildflower.component('product-page', {
    state: {}
})

// Child owns data AND handles actions
wildflower.component('product-display', {
    state: {
        product: {
            name: 'Wireless Headphones',
            description: 'Premium sound quality with noise cancellation',
            price: 149.99
        },
        addedToCart: false
    },

    // Called by button in PARENT's template
    addToCart(event, element, details) {
        // details.item contains the bound data
        console.log('Adding to cart:', details.item.name)
        this.addedToCart = true
        setTimeout(() => {
            this.addedToCart = false
        }, 2000)
    }
})
                    

Live Preview

List Binding

The same pattern works for arrays with data-list. Instead of rendering one object, the template renders for each item in the array:

                        <!-- Parent component defines HOW items should look -->
<div data-component="user-directory">
    <!-- Define a named template for user cards -->
    <template data-item-template="userCard">
        <div class="card mb-2">
            <div class="card-body d-flex align-items-center">
                <div class="rounded-circle bg-primary text-white d-flex align-items-center justify-content-center me-3"
                     style="width: 40px; height: 40px; font-weight: bold;">
                    <span data-bind="initials"></span>
                </div>
                <div class="flex-grow-1">
                    <h6 class="mb-0"><span data-bind="name"></span></h6>
                    <small class="text-muted"><span data-bind="role"></span></small>
                </div>
                <button class="btn btn-sm btn-primary" data-action="selectUser">
                    View
                </button>
            </div>
        </div>
    </template>

    <!-- The list uses the template defined above -->
    <div data-list="users">
        <template data-use-template="userCard"></template>
    </div>

    <div class="alert alert-info mt-3" data-show="selectedUser">
        Selected: <strong data-bind="selectedUser"></strong>
    </div>
</div>
                    

                        wildflower.component('user-directory', {
    state: {
        users: [
            { name: 'Alice Chen', role: 'Engineering Lead', initials: 'AC' },
            { name: 'Bob Smith', role: 'Product Designer', initials: 'BS' },
            { name: 'Carol Davis', role: 'Frontend Developer', initials: 'CD' }
        ],
        selectedUser: ''
    },

    selectUser(event, element, details) {
        // details.item contains the list item data
        this.selectedUser = details.item.name
    }
})
                    

Live Preview

Note: Inside data-list, you don't need data-with. The list automatically provides each item's data context.

Fallback Templates

If a parent template isn't found, you can provide fallback content in two ways:

Inline Fallback

Put fallback content directly inside the data-use-template element:

                        <!-- Parent does NOT define "fancyCard" template -->
<div data-component="no-template-parent">
    <div data-component="card-display">
        <!-- "fancyCard" won't be found, so fallback is used -->
        <div data-use-template="fancyCard" data-with="item">
            <!-- Inline fallback content -->
            <div class="card">
                <div class="card-body">
                    <p class="mb-0">Default: <strong data-bind="name"></strong></p>
                </div>
            </div>
        </div>
    </div>
</div>
                    

                        wildflower.component('no-template-parent', {
    state: {}
})

wildflower.component('card-display', {
    state: {
        item: { name: 'Using Fallback Template' }
    }
})
                    

Live Preview

Sibling Fallback (for lists)

Use a separate data-template-fallback element:

<div data-list="items">
    <template data-use-template="customCard"></template>
    <template data-template-fallback="customCard">
        <!-- Fallback template -->
        <div class="default-item">
            <span data-bind="name"></span>
        </div>
    </template>
</div>

Priority: Inline fallback takes precedence over sibling fallback if both are present.

Full Example: Task Manager

Here's a complete example combining lists, actions, computed properties, and configurable templates:

                        <div data-component="task-manager">
    <!-- Parent defines the template with actions -->
    <template data-item-template="taskRow">
        <div class="d-flex align-items-center p-2 border-bottom">
            <input type="checkbox" class="form-check-input me-2"
                   data-model="done">
            <span class="flex-grow-1"
                  data-bind-class="done ? 'text-decoration-line-through text-muted' : ''"
                  data-bind="title"></span>
            <!-- This action calls task-list's method, NOT task-manager's -->
            <button class="btn btn-sm btn-danger" data-action="removeTask">
                Remove
            </button>
        </div>
    </template>

    <!-- Child component uses the template -->
    <div data-component="task-list">
        <div class="mb-2 d-flex gap-2">
            <input type="text" class="form-control" data-model="newTask"
                   placeholder="Add task...">
            <button class="btn btn-primary" data-action="addTask">Add</button>
        </div>
        <div data-list="tasks">
            <template data-use-template="taskRow"></template>
        </div>
        <div class="mt-2 text-muted small">
            <span data-bind="completedCount"></span> of
            <span data-bind="totalCount"></span> completed
        </div>
    </div>
</div>
                    

                        // Parent just provides structure and template
wildflower.component('task-manager', {
    state: {}
})

// Child owns the data AND handles the actions
wildflower.component('task-list', {
    state: {
        tasks: [
            { title: 'Learn configurable templates', done: false },
            { title: 'Build something cool', done: false },
            { title: 'Read the docs', done: true }
        ],
        newTask: ''
    },

    computed: {
        totalCount() {
            return this.tasks.length
        },
        completedCount() {
            return this.tasks.filter(t => t.done).length
        }
    },

    addTask() {
        const title = this.newTask.trim()
        if (title) {
            this.tasks.push({ title, done: false })
            this.newTask = ''
        }
    },

    // This method is called by the button in the PARENT's template
    removeTask(event, element, details) {
        // Use details.index from the framework's action context
        this.tasks.splice(details.index, 1)
    }
})
                    

Live Preview

Use Cases

Themeable Components

Create list components that can be styled differently in different parts of your app without changing the component itself.

Design System Libraries

Build component libraries where consumers can customize rendering while the library handles data management.

Admin Dashboards

Let different dashboard views render the same data with different layouts (cards, tables, lists).

Content Management

Display selected items (current post, active user, etc.) using parent-defined presentation.

Best Practices

Do:

Use descriptive template names (e.g., userCard, productTile)
Provide fallback templates for reusable components
Keep action handlers in the child component that owns the data
Document which templates your components expect/provide

Avoid:

Generic names like item or template that could collide
Deeply nested template lookups (keep hierarchies shallow)
Putting complex logic in templates (keep templates presentational)

Reference

Attribute	Location	Description
`data-item-template="name"`	Parent component	Defines a named template that descendant components can use
`data-use-template="name"`	Child component	References an ancestor's template for rendering
`data-with="path"`	With `data-use-template`	Binds template to a specific state path (for single objects outside lists)
`data-use-template="name@component"`	Child component	References a specific ancestor's template (skips closer ones)
`data-template-fallback="name"`	Sibling of `data-use-template`	Fallback template if the named template isn't found
`data-wf-used-template="name"`	Rendered items	SSR marker indicating which template was used (auto-generated)

JavaScript API

Method	Description
`wildflower.rescanItemTemplates(element)`	Re-scan a component for newly added templates. Returns array of new template names.

Events

Event	Detail	Description
`itemTemplateReady`	`{ templateName, component }`	Fired when a new template is registered via `rescanItemTemplates()`

Prefix support: All attributes also support the data-wf- prefix. For example:

<template data-wf-item-template="userCard">...</template>
<template data-wf-use-template="userCard"></template>
<div data-wf-use-template="userCard" data-wf-with="user"></div>

Lifecycle & Cleanup: Templates registered during component initialization are automatically cleaned up when the component is destroyed. No manual unregistration is required.

Previous Props

Next Advanced Configurable Templates