From 17d69c3fb4cb1d051f65603d4539c57feca69fe4 Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Wed, 19 Aug 2020 17:32:34 +0300
Subject: [PATCH] Add FAQ entry about HTML entities

Closes #413
---
 doc/FAQ/HtmlEntities.md | 22 ++++++++++++++++++++++
 doc/README.md           |  1 +
 doc/cljdoc.edn          |  3 ++-
 3 files changed, 25 insertions(+), 1 deletion(-)
 create mode 100644 doc/FAQ/HtmlEntities.md

diff --git a/doc/FAQ/HtmlEntities.md b/doc/FAQ/HtmlEntities.md
new file mode 100644
index 00000000..4e89775d
--- /dev/null
+++ b/doc/FAQ/HtmlEntities.md
@@ -0,0 +1,22 @@
+# Using HTML entities
+
+React will escape HTML entities (like `&nbsp;`, `&times;`) in the text elements.
+
+You could just use literal character: `×` or unicode code, which is converted to
+the character by Cljs compiler: `\u00D7`.
+
+HTML entities work in React JSX because JSX will unescape the entity code to
+literal character.
+
+You can do the same in ClojureScript by using `goog.string/unescapeEntities`:
+
+```cljs
+(ns example
+  (:require [goog.string :as gstr]))
+
+(defn comp []
+  [:h1 "Foo" (gstr/unescapeEntities "&times;")])
+```
+
+Note: Yes, this can be inconvenient, but Reagent can't do this automatically as
+finding and replacing entities during runtime would be slow.
diff --git a/doc/README.md b/doc/README.md
index 058100d2..ff65cc4c 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -35,6 +35,7 @@ Also:
 4. [How can I use React's dangerouslySetInnerHTML?](FAQ/dangerouslySetInnerHTML.md)
 5. [Reagent doesn't work after updating dependencies](FAQ/CljsjsReactProblems.md)
 5. [How do I force Component re-creation?](FAQ/ForcingComponentRecreation.md)
+5. [Using HTML entities](FAQ/HtmlEntities.md)
 6. [How do I access "props" in lifecycle methods?](http://nils-blum-oeste.net/clojurescripts-reagent-using-props-in-lifecycle-hooks/) (external link)
 
 ## Examples
diff --git a/doc/cljdoc.edn b/doc/cljdoc.edn
index 945e028c..89d9590b 100644
--- a/doc/cljdoc.edn
+++ b/doc/cljdoc.edn
@@ -18,7 +18,8 @@
                     ["Why is my attribute (like autoFocus) missing?" {:file "doc/FAQ/MyAttributesAreMissing.md"}]
                     ["How can I use React's dangerouslySetInnerHTML?" {:file "doc/FAQ/dangerouslySetInnerHTML.md"}]
                     ["Reagent doesn't work after updating dependencies" {:file "doc/FAQ/CljsjsReactProblems.md"}]
-                    ["How do I force Component re-creation?" {:file "doc/FAQ/ForcingComponentRecreation.md"}]]
+                    ["How do I force Component re-creation?" {:file "doc/FAQ/ForcingComponentRecreation.md"}]
+                    ["Using HTML entities" {:file "doc/FAQ/HtmlEntities.md"}]]
                    ["Examples" {}
                     ["Material-UI v1" {:file "doc/examples/material-ui.md"}]]
                    ["Other" {}