Getting Started

This guide takes you from installation to a working Ornata component in an HTML-first environment.

Install

npm install ornata

If you want to enhance a page without a bundler, load the browser build from a CDN instead:

<script src="https://cdn.jsdelivr.net/npm/ornata@latest/dist/index.global.js"></script>
<script>
    const { defineComponent } = window.Ornata;
</script>

Tip

Pin a specific version in production so your deployed HTML always gets the same runtime.

Start with HTML

Write the initial markup for the desired component.

Note

Ornata treats markup as the integration surface. As the component author, you decide what your component expects from that markup and how flexible that contract should be.

<section data-counter>
    <h2>Counter</h2>
    <p>
        Count:
        <span data-count-value>0</span>
    </p>
    <button type="button" data-count-button>Increment</button>
</section>

Define a component

JavaScript

import { defineComponent } from 'ornata';

const Counter = defineComponent({
    name: 'Counter',
    state: {
        count: { default: 0 },
    },
    elements: {
        value: { query: '[data-count-value]' },
        button: { query: '[data-count-button]' },
    },
    methods: {
        increment() {
            this.state.count += 1;
        },
    },
    render: {
        value() {
            return {
                text: String(this.state.count),
            };
        },
        button() {
            return {
                events: {
                    click: () => this.methods.increment(),
                },
            };
        },
    },
});

TypeScript

import { defineComponent } from 'ornata';

interface CounterState {
    count: number;
}

const Counter = defineComponent<{
    state: CounterState;
    elements: {
        value: Element | null;
        button: Element | null;
    };
    methods: {
        increment(): void;
    };
}>({
    name: 'Counter',
    state: {
        count: { default: 0 },
    },
    elements: {
        value: { query: '[data-count-value]' },
        button: { query: '[data-count-button]' },
    },
    methods: {
        increment() {
            this.state.count += 1;
        },
    },
    render: {
        value() {
            return {
                text: String(this.state.count),
            };
        },
        button() {
            return {
                events: {
                    click: () => this.methods.increment(),
                },
            };
        },
    },
});

Mount it

Note

Every Ornata component instance is mounted to a single root element. In this example, the <section data-counter> element is the root. It defines the boundary of the instance and scopes the state, elements, and behavior associated with it.

Counter.mount('[data-counter]');

What happens when it mounts

When mount() runs, Ornata:

• resolves the required root element
• reads and prepares state
• resolves configured elements
• binds methods to the internal component instance
• runs the mount lifecycle hook if present
• performs an initial render pass for each state property

Where to go next

• Read Your First Component for a deeper walkthrough
• Read State to understand initialization, reactivity, and safety controls
• Read Mounting Instances to compare mount() and mountAll()
• Read Component Anatomy for the full shape of defineComponent()