Components Basics

Components in requery-js are built on Web Components (Custom Elements), allowing you to create reusable UI elements with their own properties, state, and behaviours.

Written By Joel

Last updated About 1 month ago


Defining a component

Components are defined using the defineComponent function:

import {
  defineComponent
} from 'https://esm.run/requery-js@0.2'

defineComponent(
  // the component name
  "rq-counter",
  // the component options
  {
    props: {
      max: 10,
    },
    store: {
      count: 0
    },
    actions: {
      inc: (ctx) {
        if (store.count < props.max) {
          ctx.store.count++
        }
      }
    },
    setup(component, props, store, actions) {
      // Bind count value to <span>
      component.query('count').text(() => store.count);

      // Resister click event and bind the disabled attribute
      component
        .query('button')
        .bind('disabled', () => store.count === props.max)
        .on('click', (evt) => {
          actions.inc();
        });
    }
});

Important

The name of the component must contain a hyphen and follow the custom element naming rules.

Using a component

Once defined, components can be used directly in HTML:

<rq-counter prop:max="5">
  <button rq="button">
    Count: <span rq="count">0</span>
  </button>
</rq-counter>

Note

You can override the initial value of a component prop using the prop: prefix on HTML attributes.

Component instances

The same component can be used multiple times on a page. Each usage creates a unique instance with its own props and state:

Important
When using multiple instances of a component on a page you must specify thekey property which is used to distinguish component instances.

<rq-counter prop:key="counter1" prop:max="5"></rq-counter>
<rq-counter prop:key="counter2" prop:max="10"></rq-counter>

Querying components

Components can be queried using the queryComponent function:

// Query the first instance of a component
const counter = queryComponent('rq-counter')

// Query specific instance by key
const todoList = queryComponent('rq-counter', 'counter2')

Component API

Components expose properties and methods for managing state, handling events, and coordinating child elements in a reactive way.

Properties

Name

Docs

Description

key

Unique identifier for the component instance

name

The custom elements tag name

props

Could not load article.

Reactive props object

store

Could not load article.

Reactive internal state object

actions

Could not load article.

Bound action methods

parent

Reference to parent component (if any)

components

Map of child components by key

elements

Map of queried elements by name

Methods

Name

Description

query(name)

Find an element by its rq attribute

on(event, handler)

Listen to component events

emit(event, value)

Dispatch a custom event

dispose()

Clean up component resources

Lifecycle Hooks

Components have a single lifecycle hook that handles both initialisation and cleanup:

setup()

The setup function runs when the component is initialised and can return an optional cleanup function:

defineComponent("my-component", {
  setup(component, props, store) {
    // Initialise state
    // Set up bindings
    // Add event handlers

    // Optional: return cleanup function
    return () => {
      // Cleanup when component is disposed
    };
  }
});

Could not load article.

Could not load article.