`js
export const useToggle = (el, props) => {
// Query for elements with toggle-* attributes
const children = useChildren(el, "toggle");
const { button, content } = children;

useEvents(button, {
click: () => {
content.toggleAttribute("hidden");
}
});
};
`

The useChildren helper provides consistent access to child elements through both singular and plural keys:

- Single element: { button: HTMLElement, buttons: [HTMLElement] }
- Multiple elements: { button: HTMLElement, buttons: [HTMLElement, HTMLElement] }

This means you can always choose the access pattern that fits your needs:
- Use singular keys (button) when you need the first element
- Use plural keys (buttons) when you need to work with all elements

`js
// Always available - no conditional checks needed
const { button, buttons, content, contents } = useChildren(el, "toggle");

// Work with the first element
button.focus();

// Work with all elements
buttons.forEach(btn => btn.disabled = true);
`

This pattern lets hooks manage their own scoped child elements, similar to how components work, but with a more focused behavior that can be attached directly to elements.

$3

A custom hook is a function that receives an element and props:

`js
(el: HTMLElement, props: object) => (() => void)?
`

You can use any native DOM APIs, other hooks, or internal helpers:

`js
export const useFocusRing = (el, props) => {
useEvents(el, {
focus: () => el.classList.add("has-focus"),
blur: () => el.classList.remove("has-focus")
});

// Optional cleanup function
return () => {
el.classList.remove("has-focus");
};
};
`

HookTML will automatically run this if you write:

`html

`

$3

You can attach multiple hooks to a single element:

`html
use-tooltip="Click to submit"
use-analytics="form-submit"
use-focus-ring
>
Submit

`

Each hook is initialized independently and receives its own props, scoped by its prefix:

`js
useTooltip(el, { value: "Click to submit" })
useAnalytics(el, { value: "form-submit" })
useFocusRing(el, {}) // — no props
`

$3

Hooks are:
1. Initialized when the element appears in the DOM
2. Updated if their attributes change
3. Cleaned up when the element is removed

If a hook returns a function, it will be called during cleanup:

`js
return () => {
// Clean up resources, event listeners, etc.
};
`

---

Components

Components are functions that group hooks and behaviors to coordinate multiple elements.

$3

Components organize related elements and their behaviors. They:
- Find and interact with child elements
- Manage shared state
- Coordinate behavior between elements
- Provide a common cleanup function

$3

While both components and hooks can group behavior, they differ in important ways:

1. Automatic Binding:
- Components are automatically bound to elements with matching class names (class="Dialog") or use-component attributes (use-component="Dialog")
- Hooks must be explicitly attached with use-* attributes

2. Child Element Access:
- Components automatically collect all children with matching prefixed attributes (dialog-header) into props.children
- Hooks must explicitly call useChildren() to access child elements

3. Purpose:
- Components are designed for organizing larger UI sections and coordinating multiple elements
- Hooks are designed for reusable, composable behaviors that can be mixed and matched

4. Scope:
- Components typically define the scope boundary for a set of related elements
- Hooks typically enhance individual elements or small groups of elements within a component

Think of components as containers that provide structure and coordination, while hooks provide specific behaviors that can be composed together.

$3

Components are bound to elements using either a class name or a use-component attribute:

`html


Both approaches bind the Counter function to the element.

You can register components manually (recommended for browser environments):

`js
import { registerComponent } from 'hooktml';
registerComponent(Counter);
`

Or let HookTML auto-register them from a directory:

`js
HookTML.start({
componentPath: "/js/components"
});
`

Auto-registration Environment Support:

- Node.js environments: Auto-registers all components in the specified directory
- Bundler environments: Limited due to static analysis requirements - manual registration recommended
- Browser environments: Manual registration required

If auto-registration isn't available, use registerComponent() to register components manually.

$3

Child elements are auto-bound using lowercase attributes prefixed with the component name:

`html


`js
export const Dialog = (el, props) => {
const { header, body, footer } = props.children;

// Now you can work with these DOM elements
header.classList.add('text-lg');
};
`

Children are matched based on attribute—not tag, class, or ID—and returned as actual DOM elements. They return both singular and plural keys, regardless of how many elements are found.

`js
const { items, item } = props.children;
// items returns an array of all matching elements
items.forEach(item => item.classList.add('list-item'));

// item returns the first matching element
item.focus();
`

$3

To pass props into a component, use custom attributes prefixed with the component name:

`html
class="Modal"
modal-open="true"
modal-size="lg"
>
`

Which becomes:

`js
props = {
open: true,
size: "lg"
};
`

$3

Components follow the same lifecycle as hooks:
1. Initialized when the element appears
2. Updated if their attributes change
3. Cleaned up when removed

Components can return a simple cleanup function:

`js
return () => {
// Clean up resources
};
`

Or a more complex object with context:

`js
return {
cleanup: () => {
// Clean up resources
},
context: {
// Methods and data to expose to other components
open, close, isOpen
}
};
`

---

Styling

HookTML encourages writing CSS that mirrors your component structure, using attribute selectors for state.

$3

You can attach styles directly to a component using Component.styles. These are injected once into a global