data-text

Overview

data-text binds data values to an element's text content. It's the most commonly used directive for displaying dynamic text.

When to use:

• Display text from data objects
• Show user information, labels, or dynamic content
• Format values with pipes (formatters)

Why use it:

• ✅ Safely displays text (XSS-safe)
• ✅ Supports formatters via pipe syntax
• ✅ Reactive - updates automatically when data changes
• ✅ Works with nested properties

Basic Usage

Simple Text Binding

<span data-text="username"></span>

With data:

{ username: "John Doe" }

Output:

<span>John Doe</span>

Nested Properties

<span data-text="user.profile.name"></span>

With data:

{
  user: {
    profile: {
      name: "Jane Smith"
    }
  }
}

Output:

<span>Jane Smith</span>

Syntax

<element data-text="expression | formatter1 | formatter2">

Pipe Parsing Rules

data-text evaluates the expression first, then applies formatters separated by top-level pipe characters.

• A single top-level | starts a formatter.
• || remains a normal JavaScript fallback operator.
• Pipes inside quoted strings are treated as text, not formatter separators.
• Pipes inside nested expressions such as (), [], and {} are ignored until the expression returns to top level.

Valid examples:

<span data-text="status || '-' "></span>
<span data-text="'Value ' + (status || '-')"></span>
<span data-text="(brand_name || '-') + ' | ' + (category_name || '-')"></span>
<span data-text="price | currency:THB"></span>

Formatter arguments are passed as raw :-separated strings. Do not wrap them in quotes.

<span data-text="price | currency:THB:th-TH:4"></span>
<span data-text="created_at | date:D MMM YYYY"></span>

|| vs default:

Use || when you want normal JavaScript fallback behavior for falsy values.

<span data-text="status || '-'"></span>

Use default: when you want a formatter-style fallback only for null and undefined.

<span data-text="status | default:-"></span>

This distinction matters:

• status || '-' replaces null, undefined, '', 0, and false
• status | default:- replaces only null and undefined

Features

1. Simple Property Binding

<p data-text="title"></p>
<p data-text="description"></p>

2. Nested Object Access

<span data-text="product.category.name"></span>
<span data-text="order.customer.email"></span>

3. Array Index Access

<span data-text="items[0].name"></span>
<span data-text="users[2].email"></span>

4. Formatters (Pipes)

Transform values using formatters:

<!-- Uppercase -->
<span data-text="name | uppercase"></span>

<!-- Lowercase -->
<span data-text="email | lowercase"></span>

<!-- Date formatting -->
<span data-text="createdAt | date:D MMM YYYY"></span>

<!-- Number formatting -->
<span data-text="price | number:2"></span>

<!-- Currency -->
<span data-text="total | currency:THB:th-TH:4"></span>

5. Chained Formatters

<span data-text="name | lowercase | capitalize"></span>

Advanced Examples

User Profile Card

<div class="profile-card">
  <h2 data-text="user.name"></h2>
  <p class="email" data-text="user.email | lowercase"></p>
  <p class="joined">
    Member since: <span data-text="user.createdAt | date:MMMM YYYY"></span>
  </p>
  <p class="status" data-text="user.status | uppercase"></p>
</div>

Product Display

<div class="product">
  <h3 data-text="product.name"></h3>
  <p class="price" data-text="product.price | currency:THB"></p>
  <p class="stock">
    In Stock: <span data-text="product.quantity | number"></span>
  </p>
  <p class="category" data-text="product.category.name"></p>
</div>

Inside data-for Loop

<ul data-for="item in items">
  <template>
    <li>
      <span class="index" data-text="index + 1"></span>.
      <span class="name" data-text="item.name"></span>
      <span class="price" data-text="item.price | currency"></span>
    </li>
  </template>
</ul>

With Fallback Values

<span data-text="user.nickname || user.name || 'Anonymous'"></span>

<span data-text="user.nickname | default:Anonymous"></span>

API Reference

Supported Expressions

Built-in Formatters

Common Pitfalls

⚠️ 1. Don't Use HTML Content

<!-- ❌ Wrong - HTML will be escaped -->
<div data-text="htmlContent"></div>
<!-- Output: &lt;strong&gt;Bold&lt;/strong&gt; -->

<!-- ✅ Correct - Use data-html -->
<div data-html="htmlContent"></div>

⚠️ 2. Property Path Case Sensitivity

<!-- ❌ Wrong - Case mismatch -->
<span data-text="user.Name"></span>  <!-- Won't work if data has 'name' -->

<!-- ✅ Correct - Match exact property name -->
<span data-text="user.name"></span>

⚠️ 3. Accessing Undefined Properties

<!-- ❌ May show 'undefined' -->
<span data-text="user.address.city"></span>

<!-- ✅ Use optional chaining or fallback -->
<span data-text="user.address?.city || 'N/A'"></span>

⚠️ 4. Picking the Wrong Fallback Type

<!-- Replaces 0 and false too, because || uses JavaScript falsy rules -->
<span data-text="qty || '-'"></span>

<!-- Keeps 0 and false, replaces only null/undefined -->
<span data-text="qty | default:-"></span>

Related Directives

• data-html - For rendering HTML content
• data-attr - For binding to attributes
• data-for - For list iteration