1 | [![</> htmx](https://raw.githubusercontent.com/bigskysoftware/htmx/master/www/img/htmx_logo.1.png "high power tools for HTML")](https://htmx.org)
|
2 |
|
3 | *high power tools for HTML*
|
4 |
|
5 | [![Discord](https://img.shields.io/discord/725789699527933952)](https://htmx.org/discord)
|
6 | [![Netlify](https://img.shields.io/netlify/dba3fc85-d9c9-476a-a35a-e52a632cef78)](https://app.netlify.com/sites/htmx/deploys)
|
7 | [![Bundlephobia](https://badgen.net/bundlephobia/dependency-count/htmx.org)](https://bundlephobia.com/result?p=htmx.org)
|
8 | [![Bundlephobia](https://badgen.net/bundlephobia/minzip/htmx.org)](https://bundlephobia.com/result?p=htmx.org)
|
9 |
|
10 | ## introduction
|
11 |
|
12 | htmx allows you to access [AJAX](https://htmx.org/docs#ajax), [CSS Transitions](https://htmx.org/docs#css_transitions),
|
13 | [WebSockets](https://htmx.org/docs#websockets) and [Server Sent Events](https://htmx.org/docs#sse)
|
14 | directly in HTML, using [attributes](https://htmx.org/reference#attributes), so you can build
|
15 | [modern user interfaces](https://htmx.org/examples) with the [simplicity](https://en.wikipedia.org/wiki/HATEOAS) and
|
16 | [power](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) of hypertext
|
17 |
|
18 | htmx is small ([~10k min.gz'd](https://unpkg.com/htmx.org/dist/)),
|
19 | [dependency-free](https://github.com/bigskysoftware/htmx/blob/master/package.json),
|
20 | [extendable](https://htmx.org/extensions) &
|
21 | IE11 compatible
|
22 |
|
23 | ## motivation
|
24 |
|
25 | * Why should only `<a>` and `<form>` be able to make HTTP requests?
|
26 | * Why should only `click` & `submit` events trigger them?
|
27 | * Why should only GET & POST be available?
|
28 | * Why should you only be able to replace the *entire* screen?
|
29 |
|
30 | By removing these arbitrary constraints htmx completes HTML as a
|
31 | [hypertext](https://en.wikipedia.org/wiki/Hypertext)
|
32 |
|
33 | ## quick start
|
34 |
|
35 | ```html
|
36 | <script src="https://unpkg.com/htmx.org@1.8.6"></script>
|
37 | <!-- have a button POST a click via AJAX -->
|
38 | <button hx-post="/clicked" hx-swap="outerHTML">
|
39 | Click Me
|
40 | </button>
|
41 | ```
|
42 |
|
43 | The [`hx-post`](https://htmx.org/attributes/hx-post) and [`hx-swap`](https://htmx.org/attributes/hx-swap) attributes tell htmx:
|
44 |
|
45 | > "When a user clicks on this button, issue an AJAX request to /clicked, and replace the entire button with the response"
|
46 |
|
47 | htmx is the successor to [intercooler.js](http://intercoolerjs.org)
|
48 |
|
49 | ### installing as a node package
|
50 |
|
51 | To install using npm:
|
52 |
|
53 | ```
|
54 | npm install htmx.org --save
|
55 | ```
|
56 |
|
57 | Note there is an old broken package called `htmx`. This is `htmx.org`.
|
58 |
|
59 | ## website & docs
|
60 |
|
61 | * <https://htmx.org>
|
62 | * <https://htmx.org/docs>
|
63 |
|
64 | ## contributing
|
65 |
|
66 | * please write code, including tests, in ES5 for [IE 11 compatibility](https://stackoverflow.com/questions/39902809/support-for-es6-in-internet-explorer-11)
|
67 | * please include test cases in [`/test`](https://github.com/bigskysoftware/htmx/tree/dev/test) and docs in [`/www`](https://github.com/bigskysoftware/htmx/tree/dev/www)
|
68 | * if you are adding a feature, consider doing it as an [extension](https://htmx.org/extensions) instead to
|
69 | keep the core htmx code tidy
|
70 | * development pull requests should be against the `dev` branch, docs fixes can be made directly against `master`
|
71 | * No time? Then [become a sponsor](https://github.com/sponsors/bigskysoftware#sponsors)
|
72 |
|
73 | ### hacking guide
|
74 |
|
75 | To develop htmx locally, you will need to install the development dependencies.
|
76 |
|
77 | __Requires Python 2 and Node 15.__
|
78 |
|
79 | Run:
|
80 |
|
81 | ```
|
82 | npm install
|
83 | ```
|
84 |
|
85 | Then, run a web server in the root.
|
86 |
|
87 | This is easiest with Python:
|
88 |
|
89 | ```
|
90 | python3 -m http.server
|
91 | ```
|
92 |
|
93 | You can then run the test suite by navigating to:
|
94 |
|
95 | <http://0.0.0.0:8000/test/>
|
96 |
|
97 | At this point you can modify `/src/htmx.js` to add features, and then add tests in the appropriate area under `/test`.
|
98 |
|
99 | * `/test/index.html` - the root test page from which all other tests are included
|
100 | * `/test/attributes` - attribute specific tests
|
101 | * `/test/core` - core functionality tests
|
102 | * `/test/core/regressions.js` - regression tests
|
103 | * `/test/ext` - extension tests
|
104 | * `/test/manual` - manual tests that cannot be automated
|
105 |
|
106 | htmx uses the [mocha](https://mochajs.org/) testing framework, the [chai](https://www.chaijs.com/) assertion framework
|
107 | and [sinon](https://sinonjs.org/releases/v9/fake-xhr-and-server/) to mock out AJAX requests. They are all OK.
|
108 |
|
109 | ## haiku
|
110 |
|
111 | *javascript fatigue:<br/>
|
112 | longing for a hypertext<br/>
|
113 | already in hand*
|