Skip to content

Commit

Permalink
docs: enhance expression handling docs with examples and relevant MDN…
Browse files Browse the repository at this point in the history
… links
  • Loading branch information
melihguleyupoglu committed Feb 12, 2025
1 parent e5e675d commit cf30a6e
Showing 1 changed file with 22 additions and 10 deletions.
32 changes: 22 additions & 10 deletions documentation/docs/03-template-syntax/01-basic-markup.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,9 +179,15 @@ A JavaScript expression can be included as text by surrounding it with curly bra

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:

- Primitive values (number, boolean, string) are directly converted to strings.
- Objects call their .toString() method (if not overridden, it defaults to [object Object]).
- Undefined and null are treated as empty strings ("").
- Primitive values (numbers, booleans, strings) are directly converted to strings.
- Objects are converted based on JavaScript’s type coercion rules:

- 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.
- 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]".
- 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.
- 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.

- undefined and null are treated as empty strings ("").
- Expressions using runes ($state, $derived, etc.) maintain their specific reactive behavior.

```svelte
Expand All @@ -190,16 +196,22 @@ When using {expression} inside markup, Svelte automatically converts the value t
let bool = false;
let obj1 = { key: "value" };
let obj2 = { toString: () => "str" };
let obj3 = { [Symbol.toPrimitive]: () => "primitive" };
let obj4 = { valueOf: () => 42, toString: () => "str" };
let obj5 = { [Symbol.toStringTag]: "CustomObject" };
let empty = undefined;
let nul = null;
<p>{emptyStr}</p> <!-- Renders as: <p></p> -->
<p>{num}</p> <!-- Renders as: <p>1</p> -->
<p>{bool}</p> <!-- Renders as: <p>false</p> -->
<p>{obj1}</p> <!-- Renders as: <p>[object Object]</p> -->
<p>{obj2}</p> <!-- Renders as: <p>str</p> -->
<p>{empty}</p> <!-- Renders as: <p></p> (empty string) -->
<p>{nul}</p> <!-- Renders as: <p></p> -->
<p>{emptyStr}</p> <!-- Renders as: <p></p> -->
<p>{num}</p> <!-- Renders as: <p>1</p> -->
<p>{bool}</p> <!-- Renders as: <p>false</p> -->
<p>{obj1}</p> <!-- Renders as: <p>[object Object]</p> -->
<p>{obj2}</p> <!-- Renders as: <p>str</p> -->
<p>{obj3}</p> <!-- Renders as: <p>primitive</p> -->
<p>{obj4}</p> <!-- Renders as: <p>str</p> (toString takes precedence) -->
<p>{obj5}</p> <!-- Renders as: <p>[object CustomObject]</p> -->
<p>{empty}</p> <!-- Renders as: <p></p> (empty string) -->
<p>{nul}</p> <!-- Renders as: <p></p> -->
```

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 `}`.
Expand Down

0 comments on commit cf30a6e

Please sign in to comment.