DOM Helpers

The this.$el helper provides jQuery-like DOM access for cases where declarative attributes aren't enough, primarily third-party library integration.

Primary Use Case: Third-Party Libraries

Most libraries need a raw DOM element to initialize. Use .el to get it:

The Code

<!-- Include Chart.js from CDN -->
<script defer src="https://cdn.jsdelivr.net/npm/chart.js"></script>

<div data-component="sales-chart">
    <div class="chart-container">
        <canvas></canvas>
    </div>
    <button data-action="addMonth">Add Month</button>
    <button data-action="toggleType">Toggle Bar/Line</button>
    <div>Total: $<span data-bind="total"></span></div>
</div>

wildflower.component('sales-chart', {
    state: {
        labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
        sales: [120, 190, 150, 220, 180, 250],
        chartType: 'bar'
    },

    computed: {
        total() { return this.sales.reduce((a, b) => a + b, 0) }
    },

    init() {
        // Get raw DOM element for Chart.js
        const canvas = this.$el('canvas').el;

        this._chart = new Chart(canvas, {
            type: this.chartType,
            data: {
                labels: this.labels.slice(),
                datasets: [{
                    label: 'Sales ($)',
                    data: this.sales.slice(),
                    borderColor: '#4361ee',
                    backgroundColor: 'rgba(67, 97, 238, 0.3)',
                    fill: true
                }]
            },
            options: { responsive: true, maintainAspectRatio: false }
        });
    },

    addMonth() {
        const months = ['Jan','Feb','Mar','Apr','May','Jun',
                        'Jul','Aug','Sep','Oct','Nov','Dec'];
        this.labels.push(months[this.labels.length % 12]);
        this.sales.push(Math.round(100 + Math.random() * 200));
        // Update Chart.js with new data
        this._chart.data.labels = this.labels.slice();
        this._chart.data.datasets[0].data = this.sales.slice();
        this._chart.update('none');
    },

    toggleType() {
        this.chartType = this.chartType === 'bar' ? 'line' : 'bar';
        this._chart.destroy();
        this.init();  // Recreate with new type
    },

    destroy() {
        // Always clean up library instances
        if (this._chart) this._chart.destroy();
    }
});

More Library Examples

// Chart.js
init() {
    const canvas = this.$el('.chart-canvas').el;
    this.chart = new Chart(canvas, {
        type: 'bar',
        data: this.chartData
    });
}

// SortableJS
init() {
    const list = this.$el('.sortable-list').el;
    this.sortable = Sortable.create(list, {
        onEnd: (evt) => {
            // Reorder state array to match new DOM order
            const item = this.items.splice(evt.oldIndex, 1)[0];
            this.items.splice(evt.newIndex, 0, item);
        }
    });
}

// Tippy.js tooltips
init() {
    this.$el('[data-tooltip]').each((el) => {
        tippy(el, { content: el.dataset.tooltip });
    });
}

See the Third-Party Libraries guide for complete integration patterns.

Secondary: Events Not Covered by data-action

Use $el for events like mouseenter, mouseleave, dragstart, scroll, or resize:

<div data-component="hover-card">
    <div class="p-4 border rounded">
        <h5>Hover over me</h5>
        <p class="details" style="display: none;">
            Extra details shown on hover!
        </p>
    </div>
</div>

wildflower.component('hover-card', {
    state: {},

    init() {
        // mouseenter/mouseleave aren't available via data-action
        this.$el('.border')
            .on('mouseenter', () => {
                this.$el('.details').show();
                this.$el('.border').css('background-color', 'var(--code-bg)');
            })
            .on('mouseleave', () => {
                this.$el('.details').hide();
                this.$el('.border').css('background-color', '');
            });
    }
    // Event handlers auto-cleanup on component destroy
});

Secondary: Focus Management

Programmatically focus inputs, useful for modals, forms, and accessibility:

wildflower.component('search-modal', {
    state: { isOpen: false },

    open() {
        this.isOpen = true;
        // Focus the input after the modal opens
        setTimeout(() => {
            this.$el('.search-input').focus();
        }, 100);
    },

    handleKeydown(event) {
        if (event.key === 'Escape') {
            this.isOpen = false;
        }
    }
});

The val() Reactivity Bridge

When setting input values programmatically, val() dispatches an input event to keep data-model in sync:

// This updates both the DOM and the reactive state
this.$el('input[data-model="search"]').val('new search term');

// Equivalent to:
// 1. element.value = 'new search term'
// 2. element.dispatchEvent(new Event('input', { bubbles: true }))

Selection Basics

API Reference