# petalframework/petal_components architecture

> Architecture diagram of the GitHub repository petalframework/petal_components, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/petalframework/petal_components
- Repository: https://github.com/petalframework/petal_components

## Overview

Petal Components is a Phoenix LiveView library of composable HEEx UI components, not a standalone application. The main workflow is that a Phoenix developer brings the library into a view and uses its component tags to render interactive UI; chat components are explicitly opted into separately. Its catalogue spans forms, data display, navigation, feedback, and visual effects. The README also describes an external MCP service for AI-assisted component discovery; it is not implemented in this repository. Some component relationships are omitted because the available excerpts do not establish their runtime calls.

Main entry points: [`lib/petal_components.ex`](https://github.com/petalframework/petal_components/blob/main/lib/petal_components.ex) (Component API), [`lib/petal_components/data_table.ex`](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/data_table.ex) (Data table), [`lib/petal_components/data_table/state.ex`](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/data_table/state.ex) (Table state), [`lib/petal_components/showcase/registry.ex`](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/showcase/registry.ex) (Showcase examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Library entry"]
  node_api["Component API"]
end

subgraph group_forms["Forms and data"]
  node_form["Form components<br/>[form.ex]"]
  node_field["Fields<br/>[field.ex]"]
  node_upload["File upload<br/>[file_upload.ex]"]
  node_filters["Filters<br/>[filters.ex]"]
  node_datatable["Data table<br/>[data_table.ex]"]
  node_table_state["Table state<br/>[state.ex]"]
  node_table_engine["List engine<br/>[list.ex]"]
end

subgraph group_ui["Interactive UI"]
  node_calendar["Calendar<br/>[calendar.ex]"]
  node_carousel["Carousel<br/>[carousel.ex]"]
  node_combo["Combo box<br/>[combo_box.ex]"]
  node_chat["Chat components<br/>[chat.ex]"]
  node_skeleton["Skeleton<br/>[skeleton.ex]"]
  node_slider["Slider<br/>[slider.ex]"]
  node_tree["Tree<br/>[tree.ex]"]
end

subgraph group_visual["Display and icons"]
  node_icons_outline["Outline icons<br/>[outline.ex]"]
  node_icons_solid["Solid icons<br/>[solid.ex]"]
end

subgraph group_showcase["Showcase"]
  node_showcase_registry["Showcase examples<br/>[registry.ex]"]
  node_chat_example["Chat showcase<br/>[chat.ex]"]
end

node_developer(("Phoenix developer"))
node_mcp{{"Hosted MCP"}}

node_developer -->|"uses components"| node_api
node_api -->|"imports"| node_form
node_api -->|"imports"| node_field
node_api -->|"imports"| node_upload
node_api -->|"imports"| node_filters
node_api -->|"imports"| node_datatable
node_api -->|"imports"| node_calendar
node_api -->|"imports"| node_carousel
node_api -->|"imports"| node_combo
node_api -->|"imports"| node_skeleton
node_api -->|"imports"| node_slider
node_api -->|"imports"| node_tree
node_api -->|"aliases icons"| node_icons_outline
node_developer -->|"opts into"| node_chat
node_datatable -.->|"uses state"| node_table_state
node_table_state -->|"drives engine"| node_table_engine
node_showcase_registry -.->|"curates example"| node_chat_example
node_mcp -->|"provides schemas"| node_developer

click node_api "https://github.com/petalframework/petal_components/blob/main/lib/petal_components.ex"
click node_form "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/form.ex"
click node_field "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/field.ex"
click node_upload "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/file_upload.ex"
click node_filters "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/filters.ex"
click node_datatable "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/data_table.ex"
click node_table_state "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/data_table/state.ex"
click node_table_engine "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/data_table/engine/list.ex"
click node_calendar "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/calendar.ex"
click node_carousel "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/carousel.ex"
click node_combo "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/combo_box.ex"
click node_chat "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/chat.ex"
click node_skeleton "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/skeleton.ex"
click node_slider "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/slider.ex"
click node_tree "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/tree.ex"
click node_icons_outline "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/icons/heroicons_v1/outline.ex"
click node_icons_solid "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/icons/heroicons_v1/solid.ex"
click node_showcase_registry "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/showcase/registry.ex"
click node_chat_example "https://github.com/petalframework/petal_components/blob/main/lib/petal_components/showcase/chat.ex"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api toneBlue
class node_form,node_field,node_upload,node_filters,node_datatable,node_table_state,node_table_engine toneAmber
class node_calendar,node_carousel,node_combo,node_chat,node_skeleton,node_slider,node_tree toneMint
class node_icons_outline,node_icons_solid toneRose
class node_showcase_registry,node_chat_example,node_developer,node_mcp toneIndigo
```

## Components

### Library entry

- [Component API](https://github.com/petalframework/petal_components/blob/main/lib/petal_components.ex): `lib/petal_components.ex`

### Forms and data

- [Form components](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/form.ex): `lib/petal_components/form.ex`
- [Fields](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/field.ex): `lib/petal_components/field.ex`
- [File upload](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/file_upload.ex): `lib/petal_components/file_upload.ex`
- [Filters](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/filters.ex): `lib/petal_components/filters.ex`
- [Data table](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/data_table.ex): `lib/petal_components/data_table.ex`
- [Table state](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/data_table/state.ex): `lib/petal_components/data_table/state.ex`
- [List engine](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/data_table/engine/list.ex): `lib/petal_components/data_table/engine/list.ex`

### Interactive UI

- [Calendar](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/calendar.ex): `lib/petal_components/calendar.ex`
- [Carousel](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/carousel.ex): `lib/petal_components/carousel.ex`
- [Combo box](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/combo_box.ex): `lib/petal_components/combo_box.ex`
- [Chat components](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/chat.ex): `lib/petal_components/chat.ex`
- [Skeleton](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/skeleton.ex): `lib/petal_components/skeleton.ex`
- [Slider](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/slider.ex): `lib/petal_components/slider.ex`
- [Tree](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/tree.ex): `lib/petal_components/tree.ex`

### Display and icons

- [Outline icons](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/icons/heroicons_v1/outline.ex): `lib/petal_components/icons/heroicons_v1/outline.ex`
- [Solid icons](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/icons/heroicons_v1/solid.ex): `lib/petal_components/icons/heroicons_v1/solid.ex`

### Showcase

- [Showcase examples](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/showcase/registry.ex): `lib/petal_components/showcase/registry.ex`
- [Chat showcase](https://github.com/petalframework/petal_components/blob/main/lib/petal_components/showcase/chat.ex): `lib/petal_components/showcase/chat.ex`

### Other components

- **Phoenix developer**
- **Hosted MCP**

## Connections

- Phoenix developer → Component API: uses components (evidence: `README.md`)
- Component API → Form components: imports (evidence: `lib/petal_components.ex`)
- Component API → Fields: imports (evidence: `lib/petal_components.ex`)
- Component API → File upload: imports (evidence: `lib/petal_components.ex`)
- Component API → Filters: imports (evidence: `lib/petal_components.ex`)
- Component API → Data table: imports (evidence: `lib/petal_components.ex`)
- Component API → Calendar: imports (evidence: `lib/petal_components.ex`)
- Component API → Carousel: imports (evidence: `lib/petal_components.ex`)
- Component API → Combo box: imports (evidence: `lib/petal_components.ex`)
- Component API → Skeleton: imports (evidence: `lib/petal_components.ex`)
- Component API → Slider: imports (evidence: `lib/petal_components.ex`)
- Component API → Tree: imports (evidence: `lib/petal_components.ex`)
- Component API → Outline icons: aliases icons (evidence: `lib/petal_components.ex`)
- Phoenix developer → Chat components: opts into
- Data table → Table state: uses state
- Table state → List engine: drives engine (evidence: `lib/petal_components/data_table/state.ex`)
- Showcase examples → Chat showcase: curates example
- Hosted MCP → Phoenix developer: provides schemas (evidence: `README.md`)
