# bigskysoftware/htmx architecture

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

- Interactive diagram: https://gitdiagram.com/bigskysoftware/htmx
- Repository: https://github.com/bigskysoftware/htmx

## Overview

htmx is a browser-side hypermedia client: HTML attributes declare when and how to request server-rendered content, and htmx applies responses to the page. The principal flow is user events through attribute processing and trigger handling, request construction and HTTP exchange, response processing, then DOM swapping and URL/history updates. The README also identifies CSS transitions, WebSockets, and server-sent events as capabilities; extension source files are not sampled, so those branches are documented but their internal links remain unverified. Core behavior is implemented in a single large source file, so internal stages share its path.

Main entry points: [`src/htmx.js`](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js) (Event triggers), [`www/themes/htmx-theme/static/js/preload.js`](https://github.com/bigskysoftware/htmx/blob/master/www/themes/htmx-theme/static/js/preload.js) (Preload extension), [`dist/ext/sse.js`](https://github.com/bigskysoftware/htmx/blob/master/dist/ext/sse.js) (Server-sent events), [`dist/ext/ws.js`](https://github.com/bigskysoftware/htmx/blob/master/dist/ext/ws.js) (WebSockets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["HTML interaction"]
  node_html["Attribute-driven HTML"]
  node_attributes["Attribute processing<br/>[htmx.js]"]
  node_triggers["Event triggers<br/>[htmx.js]"]
end

subgraph group_requests["Request lifecycle"]
  node_values["Input values<br/>[htmx.js]"]
  node_request["Request setup<br/>[htmx.js]"]
  node_http["HTTP transport<br/>[htmx.js]"]
end

subgraph group_response["Response and page"]
  node_responsehandling["Response handling<br/>[htmx.js]"]
  node_swap["DOM swapping<br/>[htmx.js]"]
  node_browser["Browser DOM and history"]
  node_transitions["CSS transitions<br/>[htmx.js]"]
end

subgraph group_extensions["Transport extensions"]
  node_extensions["Extension API<br/>[htmx.js]"]
  node_preload["Preload extension<br/>[preload.js]"]
  node_sse["Server-sent events<br/>[sse.js]"]
  node_ws["WebSockets<br/>[ws.js]"]
  node_hyperscript["_hyperscript<br/>[_hyperscript.js]"]
end

node_user(("User"))
node_server(("Application server"))

node_user -->|"fires event"| node_triggers
node_html -->|"declares behavior"| node_attributes
node_attributes -->|"configures triggers"| node_triggers
node_triggers -.->|"collects inputs"| node_values
node_triggers -.->|"starts request"| node_request
node_request -.->|"configures exchange"| node_http
node_http -->|"sends HTTP request"| node_server
node_server -->|"returns HTML"| node_http
node_http -.->|"delivers response"| node_responsehandling
node_responsehandling -.->|"applies response"| node_swap
node_swap -.->|"updates DOM"| node_browser
node_swap -->|"supports transitions"| node_transitions
node_extensions -->|"registers extension"| node_preload
node_preload -->|"preloads targets"| node_request
node_html -.->|"enables SSE"| node_sse
node_html -.->|"enables WebSockets"| node_ws
node_html -.->|"scripts behavior"| node_hyperscript

click node_attributes "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_triggers "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_values "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_request "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_http "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_responsehandling "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_swap "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_transitions "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_extensions "https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js"
click node_preload "https://github.com/bigskysoftware/htmx/blob/master/www/themes/htmx-theme/static/js/preload.js"
click node_sse "https://github.com/bigskysoftware/htmx/blob/master/dist/ext/sse.js"
click node_ws "https://github.com/bigskysoftware/htmx/blob/master/dist/ext/ws.js"
click node_hyperscript "https://github.com/bigskysoftware/htmx/blob/master/www/themes/htmx-theme/static/js/_hyperscript.js"

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_html,node_attributes,node_triggers,node_user toneBlue
class node_values,node_request,node_http toneAmber
class node_responsehandling,node_swap,node_browser,node_transitions,node_server toneMint
class node_extensions,node_preload,node_sse,node_ws,node_hyperscript toneRose
```

## Components

### HTML interaction

- **Attribute-driven HTML**
- [Attribute processing](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`
- [Event triggers](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`

### Request lifecycle

- [Input values](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`
- [Request setup](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`
- [HTTP transport](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`

### Response and page

- [Response handling](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`
- [DOM swapping](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`
- **Browser DOM and history**
- [CSS transitions](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`

### Transport extensions

- [Extension API](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js): `src/htmx.js`
- [Preload extension](https://github.com/bigskysoftware/htmx/blob/master/www/themes/htmx-theme/static/js/preload.js): `www/themes/htmx-theme/static/js/preload.js`
- [Server-sent events](https://github.com/bigskysoftware/htmx/blob/master/dist/ext/sse.js): `dist/ext/sse.js`
- [WebSockets](https://github.com/bigskysoftware/htmx/blob/master/dist/ext/ws.js): `dist/ext/ws.js`
- [_hyperscript](https://github.com/bigskysoftware/htmx/blob/master/www/themes/htmx-theme/static/js/_hyperscript.js): `www/themes/htmx-theme/static/js/_hyperscript.js`

### Other components

- **User**
- **Application server**

## Connections

- User → Event triggers: fires event (evidence: `src/htmx.js`)
- Attribute-driven HTML → Attribute processing: declares behavior (evidence: `README.md`)
- Attribute processing → Event triggers: configures triggers (evidence: `src/htmx.js`)
- Event triggers → Input values: collects inputs (evidence: `src/htmx.js`)
- Event triggers → Request setup: starts request (evidence: `src/htmx.js`)
- Request setup → HTTP transport: configures exchange (evidence: `src/htmx.js`)
- HTTP transport → Application server: sends HTTP request (evidence: `README.md`)
- Application server → HTTP transport: returns HTML (evidence: `README.md`)
- HTTP transport → Response handling: delivers response (evidence: `src/htmx.js`)
- Response handling → DOM swapping: applies response (evidence: `src/htmx.js`)
- DOM swapping → Browser DOM and history: updates DOM
- DOM swapping → CSS transitions: supports transitions (evidence: `README.md`)
- Extension API → Preload extension: registers extension (evidence: `www/themes/htmx-theme/static/js/preload.js`)
- Preload extension → Request setup: preloads targets (evidence: `www/themes/htmx-theme/static/js/preload.js`)
- Attribute-driven HTML → Server-sent events: enables SSE (evidence: `README.md`)
- Attribute-driven HTML → WebSockets: enables WebSockets (evidence: `README.md`)
- Attribute-driven HTML → _hyperscript: scripts behavior
