Skip to main content

Composition

Understand Moraine component architecture, single vs composite components, public parts, style slots, and DOM ownership.

View as Markdown

Moraine components expose styling through slots, and composite components also expose structure through attached JSX parts. Each component is either single or composite, as declared by XxxT.Kind (see the TypeScript guide).

Component Kinds#

Single Components#

A single component is one JSX element that renders its own internal DOM. Configure it with props, including items for collections, and style its slots with classes and styles.

Examples include Button, Badge, Input, Checkbox, and Accordion:

import { Button } from 'moraine'

export function Action() {
  return <Button variant="solid">Save</Button>
}

Composite Components#

A composite component exposes attached JSX parts that you arrange in your layout, so you control markup order, nested text, and layout wrappers.

Examples include Card, Dialog, Table, and Sidebar:

import { Card } from 'moraine'

export function UserCard() {
  return (
    <Card>
      <Card.Header>
        <Card.Title>Profile</Card.Title>
        <Card.Description>Manage your public identity</Card.Description>
      </Card.Header>
      <Card.Body>Main settings content</Card.Body>
      <Card.Footer>
        <Card.Action>Save changes</Card.Action>
      </Card.Footer>
    </Card>
  )
}

Parts vs Slots#

A part and a slot serve different purposes:

Concept What it is How to use
Part An attached JSX component Arranged directly in template (<Dialog.Content>)
Slot A named styling target within the component Targeted via classes={{ slotName: '...' }}
  • A public part is a real JSX component that can accept child elements, props, and DOM attributes.
  • A slot is an internal styling hook (such as contentClose or itemLabel). Slots appear in the classes and styles types and match data-slot attributes in the rendered DOM.
  • Not every slot corresponds to an attached public part. For detailed styling rules, see Customization.

DOM Ownership#

DOM Roots#

Components like Card, Button, and Input render their own top-level container element in the DOM. DOM attributes (id, aria-*, data-*, class) placed on the component pass directly to that root element.

State-only Roots#

Components like Dialog, Popover, Sheet, and BaseSelect manage reactive state and context without rendering a wrapper element in the DOM:

import { Button, Dialog } from 'moraine'

export function ModalExample() {
  return (
    // State-only root: manages open state and context, renders no wrapper <div>
    <Dialog>
      <Dialog.Trigger as={Button}>Open Modal</Dialog.Trigger>
      {/* Renders portaled DOM content */}
      <Dialog.Content title="Settings">
        <Dialog.Body>Modal Body</Dialog.Body>
      </Dialog.Content>
    </Dialog>
  )
}

In state-only roots:

  • Direct DOM attributes belong on rendered parts (such as Dialog.Content or Dialog.Trigger).
  • Setting classes or styles on the root sets default slot styles for all descendant parts.

Polymorphism (as Prop)#

Components and rendered parts that expose as support a different HTML tag or SolidJS component. State-only roots and native form controls such as Input do not expose this prop. Check the component’s API before changing its element:

import { Button } from 'moraine'

// Render a Button styled and typed as an anchor <a>
;<Button as="a" href="/docs/installation">
  Get Started
</Button>

For type preservation and event forwarding, see the Polymorphism guide.

Reading Component Anatomy#

Component documentation includes an Anatomy tree showing:

  • The hierarchy of attached public parts
  • The corresponding slot names
  • Annotations showing whether a root renders a DOM node (slot=root) or only manages state (no DOM)