WildflowerJS Logo WildflowerJS

Props

Props provide a declarative way to pass data from parent to child components, making data flow explicit and components more reusable.

Why Props?
  • Explicit data flow visible in HTML
  • Child components don't need to know parent names
  • Type validation catches errors early
  • Default values simplify component usage
  • Easier testing with mock data

Basic Props

Pass data from parent to child using data-prop-* attributes. The child defines expected props and accesses them via this.props:

<div class="card">
  <div class="card-body">
    <!-- Parent component with state -->
    <div data-component="user-profile">
        <p>Name: <span data-bind="user.name"></span></p>
        <p>Role: <span data-bind="user.role"></span></p>

        <button class="btn btn-primary btn-sm" data-action="changeUser">
            Change User
        </button>

        <hr>

        <!-- Child receives user via props -->
        <div data-component="user-badge"
             data-prop-user="user"
             data-prop-theme="primary">
            <!-- Child component HTML is inline -->
            <div class="d-flex align-items-center gap-2">
                <span class="badge bg-primary" data-bind-class="badgeClass">
                    <span data-bind="initials"></span>
                </span>
                <span>
                    <strong data-bind="props.user.name"></strong>
                    <small class="text-muted">(<span data-bind="props.user.role"></span>)</small>
                </span>
            </div>
        </div>
    </div>
  </div>
</div>
// Parent component manages user state
wildflower.component('user-profile', {
    state: {
        user: { name: 'Alice', role: 'Admin' }
    },

    changeUser() {
        const users = [
            { name: 'Alice', role: 'Admin' },
            { name: 'Bob', role: 'Editor' },
            { name: 'Carol', role: 'Viewer' }
        ];
        const current = users.findIndex(u => u.name === this.user.name);
        this.user = users[(current + 1) % users.length];
    }
})

// Child component receives data via props
wildflower.component('user-badge', {
    props: {
        user: { type: Object, required: true },
        theme: { type: String, default: 'secondary' }
    },

    computed: {
        initials() {
            return this.props.user.name.split(' ')
                .map(n => n[0]).join('').toUpperCase();
        },
        badgeClass() {
            return 'badge bg-' + this.props.theme;
        }
    }
})
Live Preview

Props vs $ Accessor

Both approaches enable component communication, but serve different purposes:

Props - Explicit Data Flow 
<div data-component="avatar"
     data-prop-user="currentUser">
  • Data flow visible in HTML
  • Child doesn't know parent name
  • Highly reusable components
  • Easy to test in isolation
$entity.path - Named Access 
<span data-bind="$user-manager.currentUser.name">
</span>
  • Access by entity name in HTML
  • Works for stores, components, plugins
  • Works across the tree
  • No computed wrapper needed

Prop Value Resolution

Prop values are resolved automatically:

  • State path. If the value is a valid identifier that exists in parent state, it resolves reactively: data-prop-name="userName"
  • String literal. If the value contains spaces or isn't found in parent state, it's treated as a literal string: data-prop-title="Hello World"
  • Number / boolean. Numeric and boolean values are parsed automatically: data-prop-count="42", data-prop-visible="true"
  • Explicit literal. Wrap in quotes to force a literal when the value matches a state name: data-prop-label="'name'"

Passing Multiple Props with data-props

Pass multiple props in a single attribute using object expression syntax:

<!-- Object expression: values resolve from parent state -->
<div data-component="card"
     data-props="{ title: cardTitle, color: accentColor }">

<!-- Equivalent to individual attributes: -->
<div data-component="card"
     data-prop-title="cardTitle"
     data-prop-color="accentColor">

Values resolve from parent state and update reactively when the parent state changes. Quoted string values can contain commas: data-props="{ label: 'hello, world', color: color }".

data-prop-* attributes override data-props values when both are present on the same element.

Default Values

Provide defaults for optional props. Use factory functions for objects and arrays to ensure each instance gets its own copy:

<div class="card">
  <div class="card-body">
    <div data-component="defaults-demo">
        <div class="d-flex flex-column gap-3">
            <!-- Card with all defaults -->
            <div data-component="info-card">
                <div class="card border-primary" data-bind-class="cardClass">
                    <div class="card-header bg-primary text-white" data-bind-class="headerClass">
                        <span data-bind="props.title"></span>
                    </div>
                    <div class="card-body">
                        <p class="mb-0">Count: <strong data-bind="props.count"></strong></p>
                    </div>
                </div>
            </div>

            <!-- Card with custom title (plain text = literal) -->
            <div data-component="info-card"
                 data-prop-title="Custom Title"
                 data-prop-variant="success">
                <div class="card border-success" data-bind-class="cardClass">
                    <div class="card-header bg-success text-white" data-bind-class="headerClass">
                        <span data-bind="props.title"></span>
                    </div>
                    <div class="card-body">
                        <p class="mb-0">Count: <strong data-bind="props.count"></strong></p>
                    </div>
                </div>
            </div>

            <!-- Card with state-driven props -->
            <div data-component="info-card"
                 data-prop-title="cardTitle"
                 data-prop-count="clickCount"
                 data-prop-variant="warning">
                <div class="card border-warning" data-bind-class="cardClass">
                    <div class="card-header bg-warning text-white" data-bind-class="headerClass">
                        <span data-bind="props.title"></span>
                    </div>
                    <div class="card-body">
                        <p class="mb-0">Count: <strong data-bind="props.count"></strong></p>
                    </div>
                </div>
            </div>
        </div>

        <button class="btn btn-primary mt-3" data-action="incrementCount">
            Increment Count (affects 3rd card)
        </button>
    </div>
  </div>
</div>
wildflower.component('defaults-demo', {
    state: {
        cardTitle: 'Dynamic Card',
        clickCount: 0
    },

    incrementCount() {
        this.clickCount++;
    }
})

wildflower.component('info-card', {
    props: {
        // Primitive default - use directly
        title: {
            type: String,
            default: 'Default Title'
        },
        count: {
            type: Number,
            default: 0
        },
        variant: {
            type: String,
            default: 'primary'
        },
        // Object default - MUST use factory function!
        // This ensures each instance gets its own copy
        config: {
            type: Object,
            default: () => ({ showBorder: true })
        }
    },

    computed: {
        cardClass() {
            return 'card border-' + this.props.variant;
        },
        headerClass() {
            return 'card-header bg-' + this.props.variant + ' text-white';
        }
    }
})
Live Preview
Important: Always use factory functions () => ({}) for object and array defaults. Using a direct reference like default: {} means all instances share the same object, causing bugs when one instance modifies it.

Type Validation

Props support type checking with String, Number, Boolean, Array, Object, and Function. In development mode, type mismatches throw errors; in production, they log warnings:

<div class="card">
  <div class="card-body">
    <div data-component="validation-demo">
        <!-- Progress bar with validated props -->
        <div data-component="progress-bar"
             data-prop-value="progress"
             data-prop-show-percentage="true"
             data-prop-animated="isAnimated">
            <!-- Child component HTML inline -->
            <div class="progress" style="height: 25px;">
                <div class="progress-bar-inner" data-bind-class="barClass"
                     role="progressbar">
                    <span data-bind="displayText"></span>
                </div>
            </div>
        </div>

        <div class="mt-3">
            <button class="btn btn-danger btn-sm" data-action="decreaseProgress">
                -10%
            </button>
            <button class="btn btn-success btn-sm" data-action="increaseProgress">
                +10%
            </button>
            <button class="btn btn-secondary btn-sm" data-action="toggleAnimation">
                Toggle Animation
            </button>
        </div>

        <p class="mt-2 mb-0 small text-muted">
            Progress: <span data-bind="progress"></span>% |
            Animated: <span data-bind="isAnimated"></span>
        </p>
    </div>
  </div>
</div>
wildflower.component('validation-demo', {
    state: {
        progress: 45,
        isAnimated: true
    },

    increaseProgress() {
        this.progress = Math.min(100, this.progress + 10);
    },

    decreaseProgress() {
        this.progress = Math.max(0, this.progress - 10);
    },

    toggleAnimation() {
        this.isAnimated = !this.isAnimated;
    }
})

wildflower.component('progress-bar', {
    props: {
        // Number type with custom validator
        value: {
            type: Number,
            required: true,
            validator: (v) => v >= 0 && v <= 100
        },
        // Boolean type
        showPercentage: {
            type: Boolean,
            default: true
        },
        // Boolean type
        animated: {
            type: Boolean,
            default: false
        }
    },

    computed: {
        barClass() {
            var cls = 'progress-bar';
            if (this.props.animated) {
                cls += ' progress-bar-striped progress-bar-animated';
            }
            return cls;
        },
        displayText() {
            if (this.props.showPercentage) return this.props.value + '%';
            return '';
        }
    },

    // Called when any prop value changes: useful for imperative
    // DOM updates that can't be expressed with data-bind
    onPropsChange() {
        this.updateBarWidth();
    },

    updateBarWidth() {
        var bar = this.element.querySelector('.progress-bar-inner');
        if (bar) bar.style.width = this.props.value + '%';
    },

    init() {
        this.updateBarWidth();
    }
})
Live Preview

Supported Types

Type JavaScript Value Example Prop Value
String 'hello' data-prop-name="John" (literal) or data-prop-name="userName" (state)
Number 42 data-prop-count="42" or data-prop-count="itemCount"
Boolean true / false data-prop-visible="true" or data-prop-visible="isShown"
Array [1, 2, 3] data-prop-items="todoList"
Object { key: 'value' } data-prop-config="settings"
Function () => {} data-prop-on-click="handleClick"

Function Props (Callbacks)

Pass parent methods as props to enable child-to-parent communication. This is the recommended pattern for children to notify parents of events:

<div class="card">
  <div class="card-body">
    <div data-component="counter-parent">
        <p>Parent count: <strong data-bind="count"></strong></p>

        <!-- Child receives callback to notify parent -->
        <div data-component="counter-buttons"
             data-prop-on-increment="handleIncrement"
             data-prop-on-decrement="handleDecrement"
             data-prop-on-reset="handleReset">
            <button class="btn btn-danger" data-action="decrement">-1</button>
                <button class="btn btn-success" data-action="increment">+1</button>
                <button class="btn btn-secondary" data-action="reset">Reset</button>
        </div>

        <hr>

        <!-- Another child with different callbacks -->
        <div data-component="counter-buttons"
             data-prop-on-increment="handleBigIncrement"
             data-prop-on-decrement="handleBigDecrement">
            <button class="btn btn-danger" data-action="decrement">-10</button>
                <button class="btn btn-success" data-action="increment">+10</button>
        </div>
    </div>
  </div>
</div>
// Parent manages state and provides callbacks
wildflower.component('counter-parent', {
    state: {
        count: 0
    },

    // Callbacks passed to first child
    handleIncrement() {
        this.count += 1;
    },

    handleDecrement() {
        this.count -= 1;
    },

    handleReset() {
        this.count = 0;
    },

    // Callbacks for second child (bigger increments)
    handleBigIncrement() {
        this.count += 10;
    },

    handleBigDecrement() {
        this.count -= 10;
    }
})

// Reusable button component - calls parent callbacks
wildflower.component('counter-buttons', {
    props: {
        onIncrement: { type: Function },
        onDecrement: { type: Function },
        onReset: { type: Function }
    },

    increment() {
        if (this.props.onIncrement) {
            this.props.onIncrement();
        }
    },

    decrement() {
        if (this.props.onDecrement) {
            this.props.onDecrement();
        }
    },

    reset() {
        if (this.props.onReset) {
            this.props.onReset();
        }
    }
})
Live Preview

Props Definition Reference

Full Syntax

wildflower.component('my-component', {
    props: {
        // Full definition with all options
        propName: {
            type: String,              // Constructor: String, Number, Boolean, Array, Object, Function
            required: false,           // Boolean - throws/warns if missing when true
            default: 'value',          // Default value (use factory for objects/arrays)
            validator: (v) => true     // Custom validation function
        }
    }
})

Shorthand Syntax

For simple props, use type-only shorthand:

wildflower.component('button', {
    props: {
        label: String,      // Shorthand: just the type
        disabled: Boolean,
        onClick: Function
    }
})

Prop Value Formats

Format Example Resolves To
State path data-prop-user="currentUser" Parent's state.currentUser
Nested path data-prop-name="user.profile.name" Parent's state.user.profile.name
String literal data-prop-title="Hello World" 'Hello World'
Number literal data-prop-count="42" 42
Boolean literal data-prop-visible="true" true
Computed property data-prop-total="computed:orderTotal" Parent's computed orderTotal
Parent method data-prop-on-click="handleClick" Parent's handleClick method (bound)

Best Practices

Do
  • Use props for parent-to-child data flow
  • Define types for documentation and validation
  • Use factory functions for object/array defaults
  • Pass callbacks for child-to-parent communication
  • Keep props minimal and focused
  • Use required: true for essential props
Don't
  • Modify props directly (they're read-only)
  • Use object literals as defaults without factories
  • Pass too many props (consider restructuring)
  • Use props for global state (use stores instead)
  • Forget to handle missing optional props

Ready to learn more?

Now that you understand props, explore how components communicate in other ways and manage their lifecycle.

Component Basics Lifecycle Hooks Global Stores
Related patterns: Parent-Child Props
Previous Slots
Next Configurable Templates