Skip to content

Commit cf30a6e

Browse files
docs: enhance expression handling docs with examples and relevant MDN links
1 parent e5e675d commit cf30a6e

File tree

1 file changed

+22
-10
lines changed

1 file changed

+22
-10
lines changed

documentation/docs/03-template-syntax/01-basic-markup.md

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -179,9 +179,15 @@ A JavaScript expression can be included as text by surrounding it with curly bra
179179

180180
When using {expression} inside markup, Svelte automatically converts the value to a string before rendering it and makes the expression reactive (similar to wrapping it in $derived). The conversion follows JavaScript's standard behavior:
181181

182-
- Primitive values (number, boolean, string) are directly converted to strings.
183-
- Objects call their .toString() method (if not overridden, it defaults to [object Object]).
184-
- Undefined and null are treated as empty strings ("").
182+
- Primitive values (numbers, booleans, strings) are directly converted to strings.
183+
- Objects are converted based on JavaScript’s type coercion rules:
184+
185+
- If an object defines a [Symbol.toPrimitive](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, it takes precedence and determines how the object is converted.
186+
- Otherwise, if a [toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) method is present, it is called. If not overridden, it defaults to "[object Object]".
187+
- If toString() is not available or does not return a primitive, JavaScript may fall back to [valueOf()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf), which may be used if it returns a primitive value.
188+
- Additionally, an object with a [Symbol.toStringTag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property affects how it is represented when coerced to a string.
189+
190+
- undefined and null are treated as empty strings ("").
185191
- Expressions using runes ($state, $derived, etc.) maintain their specific reactive behavior.
186192

187193
```svelte
@@ -190,16 +196,22 @@ When using {expression} inside markup, Svelte automatically converts the value t
190196
let bool = false;
191197
let obj1 = { key: "value" };
192198
let obj2 = { toString: () => "str" };
199+
let obj3 = { [Symbol.toPrimitive]: () => "primitive" };
200+
let obj4 = { valueOf: () => 42, toString: () => "str" };
201+
let obj5 = { [Symbol.toStringTag]: "CustomObject" };
193202
let empty = undefined;
194203
let nul = null;
195204
196-
<p>{emptyStr}</p> <!-- Renders as: <p></p> -->
197-
<p>{num}</p> <!-- Renders as: <p>1</p> -->
198-
<p>{bool}</p> <!-- Renders as: <p>false</p> -->
199-
<p>{obj1}</p> <!-- Renders as: <p>[object Object]</p> -->
200-
<p>{obj2}</p> <!-- Renders as: <p>str</p> -->
201-
<p>{empty}</p> <!-- Renders as: <p></p> (empty string) -->
202-
<p>{nul}</p> <!-- Renders as: <p></p> -->
205+
<p>{emptyStr}</p> <!-- Renders as: <p></p> -->
206+
<p>{num}</p> <!-- Renders as: <p>1</p> -->
207+
<p>{bool}</p> <!-- Renders as: <p>false</p> -->
208+
<p>{obj1}</p> <!-- Renders as: <p>[object Object]</p> -->
209+
<p>{obj2}</p> <!-- Renders as: <p>str</p> -->
210+
<p>{obj3}</p> <!-- Renders as: <p>primitive</p> -->
211+
<p>{obj4}</p> <!-- Renders as: <p>str</p> (toString takes precedence) -->
212+
<p>{obj5}</p> <!-- Renders as: <p>[object CustomObject]</p> -->
213+
<p>{empty}</p> <!-- Renders as: <p></p> (empty string) -->
214+
<p>{nul}</p> <!-- Renders as: <p></p> -->
203215
```
204216

205217
Curly braces can be included in a Svelte template by using their [HTML entity](https://developer.mozilla.org/docs/Glossary/Entity) strings: `&lbrace;`, `&lcub;`, or `&#123;` for `{` and `&rbrace;`, `&rcub;`, or `&#125;` for `}`.

0 commit comments

Comments
 (0)