UNPKG

4.59 kBMarkdownView Raw
1[![</> htmx](https://raw.githubusercontent.com/bigskysoftware/htmx/master/www/static/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
12htmx 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)
14directly 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
18htmx is small ([~14k 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) &
21IE11 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
30By 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.9.5"></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
43The [`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
47htmx is the successor to [intercooler.js](http://intercoolerjs.org)
48
49### installing as a node package
50
51To install using npm:
52
53```
54npm install htmx.org --save
55```
56
57Note 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* All PRs should be made against the `dev` branch, except documentation PRs (`www/` directory) which can be made against `master`
67* Please write code, including tests, in ES5 for [IE 11 compatibility](https://stackoverflow.com/questions/39902809/support-for-es6-in-internet-explorer-11)
68* 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)
69* Search the issues before proposing a feature to see if it is already under discussion
70* If you are adding a feature, consider doing it as an [extension](https://htmx.org/extensions) instead to keep the core htmx code tidy
71* Want to contribute but don't know where to start? Look for issues with the "help wanted" tag
72* Refactors that do not make functional changes will be automatically closed, unless explicitly solicited (documentation typo fixes are fine)
73* No time? Then [become a sponsor](https://github.com/sponsors/bigskysoftware#sponsors)
74
75### hacking guide
76
77To develop htmx locally, you will need to install the development dependencies.
78
79__Requires Node 15.__
80
81Run:
82
83```
84npm install
85```
86
87Then, run a web server in the root.
88
89This is easiest with:
90
91```
92npx serve
93```
94
95You can then run the test suite by navigating to:
96
97<http://0.0.0.0:3000/test/>
98
99At this point you can modify `/src/htmx.js` to add features, and then add tests in the appropriate area under `/test`.
100
101* `/test/index.html` - the root test page from which all other tests are included
102* `/test/attributes` - attribute specific tests
103* `/test/core` - core functionality tests
104* `/test/core/regressions.js` - regression tests
105* `/test/ext` - extension tests
106* `/test/manual` - manual tests that cannot be automated
107
108htmx uses the [mocha](https://mochajs.org/) testing framework, the [chai](https://www.chaijs.com/) assertion framework
109and [sinon](https://sinonjs.org/releases/v9/fake-xhr-and-server/) to mock out AJAX requests. They are all OK.
110
111## haiku
112
113*javascript fatigue:<br/>
114longing for a hypertext<br/>
115already in hand*