--- url: /guide/concepts/composition.md --- # Composition The library separates ready-to-use solutions from reusable building blocks. Classification describes an item's primary role, not whether it has markup or can mount directly. ## Choose the right abstraction | Need | Prefer | Example | | --- | --- | --- | | A complete interaction or interface solution | Component | [`Dialog`](/reference/items/Dialog/), [`Slider`](/reference/items/Slider/) | | Lower-level behavior to compose or extend | Primitive | [`Transition`](/reference/items/Transition/), [`Indexable`](/reference/items/Indexable/) | | Reusable behavior applied to a class | Decorator | [`withTransition`](/reference/items/withTransition/), [`withIndex`](/reference/items/withIndex/) | | A standalone operation | Helper | [`viewTransition`](/reference/items/view-transition-helper/) | | Local behavior expressed in markup | Declarative component | [`Action`](/reference/items/Action/), the [Data family](./index.md#the-data-family) | | Coordination across unrelated page features | Application component | [`createApp`](./declarative-runtime.md#when-to-use-createapp) | Start at the highest-level abstraction that satisfies the requirement. Moving to a lower-level primitive or custom class gives more control but also makes the application responsible for more state, structure and accessibility behavior. ## Compound component families A compound component divides one feature into a root orchestrator and focused children. The root registers child classes through its js-toolkit `components` configuration, and markup declares the hierarchy: ```html
…
``` The `Accordion` family includes its item behavior and public contracts. Other examples include Slider, Carousel, Menu, Frame, ScrollAnimation and MapboxMap. A family's canonical Reference page documents related symbols together even when consumers can import those symbols independently. Use an item's **Anatomy** page when its child hierarchy, matching refs or required structure forms part of the contract. ## Co-located components Several independent behaviors can share one element through a space-separated `data-component` value: ```html Next page ``` Co-location is useful when each behavior can operate independently. Prefer a compound family when children exchange events, inherit configuration or depend on a specific hierarchy. ## Class composition with decorators A decorator accepts a js-toolkit component class and returns a class with an additional contract: ```js import { Base } from '@studiometa/js-toolkit'; import { withTransition } from '@studiometa/ui'; class Disclosure extends withTransition(Base) { // Disclosure-specific behavior } ``` Decorators keep cross-cutting behavior reusable without forcing unrelated classes into one inheritance hierarchy. Apply only decorators whose options, refs and lifecycle requirements the component can satisfy. ## Extending primitives Extend a primitive when it provides the correct state or service model but the application needs a specialized public behavior: ```js import { Transition } from '@studiometa/ui'; class DisclosureTransition extends Transition { open() { return this.enter(); } close() { return this.leave(); } } ``` Before extending, check whether a component already solves the interaction, whether options can configure it, or whether a decorator exposes the same capability with less custom code. ## Customization decision Use the narrowest supported boundary: 1. Set a documented JavaScript option or Twig parameter. 2. Fill a Twig block or pass root attributes. 3. Compose existing components on the same element or in a documented family. 4. Apply a public decorator or extend a public primitive. 5. Extend or override a package Twig template. 6. Create an application component for cross-feature coordination. 7. Build a new reusable component only when none of the existing contracts fit. Keeping customization at a public boundary makes upgrades easier and leaves internal implementation details free to change. ## Related concepts * [Declarative runtime](./declarative-runtime.md) * [Templates and customization](./templates-and-customization.md) * [Reference taxonomy](/reference/)