Your First Component

The easiest way to learn Ornata is to enhance a small piece of existing HTML with a clear component contract.

The markup

Note

Even without JavaScript, the HTML can still provide meaningful content from the start. How much it provides depends on you, the constraints of your environment, and the kind of component you are building.

<section data-disclosure>
    <button data-disclosure-button>Show details</button>
    <div hidden data-disclosure-panel>
        <p>Details ...</p>
    </div>
</section>

The component

JavaScript

import { defineComponent } from 'ornata';

const Disclosure = defineComponent({
    name: 'Disclosure',
    state: {
        open: { default: false, type: Boolean },
        openLabel: { default: 'Hide details' },
        closedLabel: { default: 'Show details' },
    },
    elements: {
        button: { query: '[data-disclosure-button]' },
        panel: { query: '[data-disclosure-panel]' },
    },
    methods: {
        toggle() {
            this.state.open = !this.state.open;
        },
    },
    watch: {
        open({ newValue, oldValue, isInitial }) {
            if (isInitial) return;

            console.log(
                `Disclosure's open state changed from ${oldValue} to ${newValue}`
            );
        },
    },
    computed: {
        buttonLabel() {
            if (this.state.open) return this.state.openLabel;
            return this.state.closedLabel;
        },
    },
    render: {
        button() {
            return {
                text: this.computed.buttonLabel,
                attributes: {
                    type: 'button',
                    'aria-expanded': String(this.state.open),
                },
                events: {
                    click: () => this.methods.toggle(),
                },
            };
        },
        panel() {
            return {
                attributes: {
                    hidden: !this.state.open,
                },
            };
        },
    },
});

TypeScript

import { defineComponent } from 'ornata';

interface DisclosureState {
    open: boolean;
    openLabel: string;
    closedLabel: string;
}

const Disclosure = defineComponent<{
    state: DisclosureState;
    elements: {
        button: Element | null;
        panel: Element | null;
    };
    methods: {
        toggle(): void;
    };
    computed: {
        buttonLabel: string;
    };
}>({
    name: 'Disclosure',
    state: {
        open: { default: false, type: Boolean },
        openLabel: { default: 'Hide details' },
        closedLabel: { default: 'Show details' },
    },
    elements: {
        button: { query: '[data-disclosure-button]' },
        panel: { query: '[data-disclosure-panel]' },
    },
    methods: {
        toggle() {
            this.state.open = !this.state.open;
        },
    },
    watch: {
        open({ newValue, oldValue, isInitial }) {
            if (isInitial) return;

            console.log(
                `Disclosure's open state changed from ${oldValue} to ${newValue}`
            );
        },
    },
    computed: {
        buttonLabel() {
            if (this.state.open) return this.state.openLabel;
            return this.state.closedLabel;
        },
    },
    render: {
        button() {
            return {
                text: this.computed.buttonLabel,
                attributes: {
                    type: 'button',
                    'aria-expanded': String(this.state.open),
                },
                events: {
                    click: () => this.methods.toggle(),
                },
            };
        },
        panel() {
            return {
                attributes: {
                    hidden: !this.state.open,
                },
            };
        },
    },
});

The mounting code

const disclosure = Disclosure.mount('[data-disclosure]');

Note

mount() returns the component instance, so surrounding integration code can interact with its public state or dispose of it later.

console.log(disclosure.state.open);
disclosure.state.open = true;
disclosure.dispose();

How to read this component

Each top-level option has a clear job:

• state defines reactive values
• elements finds important DOM nodes inside the root
• methods defines reusable internal behavior
• watch reacts to state changes
• computed derives values from state
• render applies DOM updates to resolved elements

That separation is one of Ornata’s main strengths. It keeps the contract between markup, behavior, and state visible, which makes the component easier to reuse in larger HTML-first systems.

Next

Continue to Component Anatomy for a deeper look at every option section.

If you want a fuller walkthrough of Ornata’s explicit typing patterns and TypeScript helpers, read TypeScript.