Relation

The Relation component (ui:relation) renders entity-relationship (ER) diagrams with entities, typed attributes, and cardinality-annotated relationships. It builds on the same graph abstraction as ui:graph but constrains the model for database and domain modeling use cases.

Example

View Glyph Markdown source

```ui:relation
entities:
  - id: users
    label: Users
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: email
        type: varchar
      - name: created_at
        type: timestamp
  - id: posts
    label: Posts
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: title
        type: varchar
      - name: body
        type: text
      - name: author_id
        type: uuid
  - id: comments
    label: Comments
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: body
        type: text
      - name: post_id
        type: uuid
      - name: user_id
        type: uuid
relationships:
  - from: users
    to: posts
    label: authors
    cardinality: "1:N"
  - from: posts
    to: comments
    label: has
    cardinality: "1:N"
  - from: users
    to: comments
    label: writes
    cardinality: "1:N"
layout: left-right
```

Many-to-many relationships

Use N:M cardinality to show many-to-many relationships. Junction tables are typically used to implement these in databases.

View Glyph Markdown source

```ui:relation
entities:
  - id: students
    label: Students
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: name
        type: varchar
      - name: email
        type: varchar
  - id: enrollments
    label: Enrollments
    attributes:
      - name: student_id
        type: uuid
        primaryKey: true
      - name: course_id
        type: uuid
        primaryKey: true
      - name: enrolled_at
        type: timestamp
      - name: grade
        type: varchar
  - id: courses
    label: Courses
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: title
        type: varchar
      - name: credits
        type: integer
relationships:
  - from: students
    to: enrollments
    label: enrolls
    cardinality: "1:N"
  - from: courses
    to: enrollments
    label: has
    cardinality: "1:N"
layout: left-right
```

Self-referential relationships

Entities can reference themselves, useful for hierarchical data like organizational structures or nested categories.

View Glyph Markdown source

```ui:relation
entities:
  - id: employees
    label: Employees
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: name
        type: varchar
      - name: title
        type: varchar
      - name: manager_id
        type: uuid
      - name: department_id
        type: uuid
  - id: departments
    label: Departments
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: name
        type: varchar
      - name: parent_id
        type: uuid
      - name: head_id
        type: uuid
relationships:
  - from: employees
    to: employees
    label: reports to
    cardinality: "N:1"
  - from: departments
    to: departments
    label: parent of
    cardinality: "1:N"
  - from: employees
    to: departments
    label: belongs to
    cardinality: "N:1"
  - from: departments
    to: employees
    label: headed by
    cardinality: "1:1"
layout: top-down
```

Complex ERD with multiple entities

A comprehensive e-commerce database schema with 6 entities and various relationship types.

View Glyph Markdown source

```ui:relation
entities:
  - id: customers
    label: Customers
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: email
        type: varchar
      - name: name
        type: varchar
      - name: created_at
        type: timestamp
  - id: orders
    label: Orders
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: customer_id
        type: uuid
      - name: status
        type: varchar
      - name: total
        type: decimal
      - name: placed_at
        type: timestamp
  - id: order_items
    label: Order Items
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: order_id
        type: uuid
      - name: product_id
        type: uuid
      - name: quantity
        type: integer
      - name: unit_price
        type: decimal
  - id: products
    label: Products
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: sku
        type: varchar
      - name: name
        type: varchar
      - name: price
        type: decimal
      - name: category_id
        type: uuid
  - id: categories
    label: Categories
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: name
        type: varchar
      - name: parent_id
        type: uuid
  - id: reviews
    label: Reviews
    attributes:
      - name: id
        type: uuid
        primaryKey: true
      - name: product_id
        type: uuid
      - name: customer_id
        type: uuid
      - name: rating
        type: integer
      - name: comment
        type: text
relationships:
  - from: customers
    to: orders
    label: places
    cardinality: "1:N"
  - from: orders
    to: order_items
    label: contains
    cardinality: "1:N"
  - from: products
    to: order_items
    label: included in
    cardinality: "1:N"
  - from: categories
    to: products
    label: contains
    cardinality: "1:N"
  - from: categories
    to: categories
    label: parent of
    cardinality: "1:N"
  - from: customers
    to: reviews
    label: writes
    cardinality: "1:N"
  - from: products
    to: reviews
    label: has
    cardinality: "1:N"
layout: left-right
```

Properties

Property	Type	Required	Default	Description
entities	Entity[]	Yes	—	An array of entity objects to render as ER diagram boxes.
relationships	Relationship[]	Yes	—	An array of relationship objects connecting entities.
layout	"top-down" | "left-right"	No	—	Layout direction for the diagram.
interactionMode	"modifier-key" | "click-to-activate" | "always"	No	"modifier-key"	Controls zoom/pan behavior.

Entity object

Property	Type	Required	Default	Description
id	string	Yes	—	Unique identifier for the entity. Referenced by relationships.
label	string	Yes	—	Display name shown in the entity header.
attributes	Attribute[]	No	—	An array of typed attributes displayed inside the entity box.

Attribute object

Property	Type	Required	Default	Description
name	string	Yes	—	The attribute name (e.g. column name).
type	string	Yes	—	The data type (e.g. “uuid”, “varchar”, “integer”, “timestamp”).
primaryKey	boolean	No	—	Whether this attribute is part of the primary key. Shown with a key icon.

Relationship object

Property	Type	Required	Default	Description
from	string	Yes	—	The id of the source entity.
to	string	Yes	—	The id of the target entity.
label	string	No	—	Text displayed on the relationship line.
cardinality	"1:1" | "1:N" | "N:1" | "N:M"	Yes	—	The cardinality of the relationship, rendered with crow’s foot notation.

Cardinality notation

Relationships are drawn with crow’s foot notation:

Cardinality	Meaning	Notation
1:1	One-to-one	Single line on both ends
1:N	One-to-many	Single line on source, crow’s foot on target
N:1	Many-to-one	Crow’s foot on source, single line on target
N:M	Many-to-many	Crow’s foot on both ends

Interaction Modes

The relation diagram supports three interaction modes for zooming and panning:

• modifier-key (default): Hold Ctrl/Cmd while scrolling to zoom. Best for scrollable content.
• click-to-activate: Click once to activate zoom/pan, Escape to deactivate. Best for explicit opt-in.
• always: Scroll immediately zooms with no modifier required. Legacy behavior.

See the Graph component documentation for detailed examples and use cases.

Shared abstraction with Graph

The Relation component shares a unified relational abstraction with Graph. While ui:graph is general-purpose, ui:relation constrains the model by:

• Requiring cardinality on every relationship (edge).
• Treating nodes as entities with typed attributes.
• Rendering entities as ER-diagram boxes rather than simple graph nodes.

Accessibility

• The ER diagram is rendered inside an SVG with role="img" and a descriptive aria-label.
• Each entity box is focusable and exposes its label and attribute list through aria-label.
• Relationship cardinalities are described in a visually hidden text summary for screen readers.
• Primary key attributes are marked with both a visual key icon and a screen-reader-accessible label.