Placeholders

\[[ variable_name ]], <cv-placeholder/>

Placeholders let readers personalise your site to their own context. Define them once in your configuration — readers fill them in via the settings panel or a <cv-placeholder-input>, and every instance across the site updates immediately. Values persist across page reloads and navigation.

Hello, \[[username]]!

<img src="https://github.com/\[[username : custardui ]].png" class="cv-bind"/>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Basic Syntax

Wrap a placeholder name in double square brackets to insert its current value:

Hello, \[[username]]!
Fork your repo at github.com/\[[username]]/ip

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The plugin scans the page on load and replaces all tokens with the current value. When the reader updates the value, all instances on the page update immediately with no reload needed.

Inline Fallback Value

Provide a fallback value directly in the syntax without needing a config entry or for defining a specific fallback for an instance:

Clone your repo: `git clone https://github.com/cs2103t/\[[repo : custom-fallback]]-ip.git`

%%Or rely on the default value in your configuration (your-repo-name)%%

Clone your repo: `git clone https://github.com/cs2103t/\[[repo]]-ip.git`

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

When a placeholder is used, CustardUI resolves its value in this order, stopping at the first match:

Conditional Syntax

Render content only when a placeholder has a value:

\[[username ? if-set, $ : if-unset]]

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

When username is unset, 'if-unset' is shown. When username is alice, 'if-set' is shown with the username value.

Conditional Syntax and defaultValue

By default, the conditional only triggers when the reader has explicitly entered a value. A defaultValue in config does not count as "set". Append * to also trigger on registry defaults:

With defaultValue: "Guest" and no user input:

HTML Attribute Binding

Interpolate placeholder values into HTML attributes such as href or src by adding class="cv-bind" to the element. This works for dynamic links, image sources, and any other attribute value. This also works with conditional syntax to build attribute values that depend on whether a placeholder is set.

CODE:

<!-- Dynamic link -->
<a href="https://github.com/\[[username : custardui]]" class="cv-bind" target="_blank">
  View \[[username : CustardUI]]'s profile on GitHub
</a>

<!-- Dynamic image source -->
<img src="https://github.com/\[[username : custardui]].png" 
  style="height: 2.5rem; vertical-align: middle; border-radius: 50%; margin-left: 0.5rem;" 
  class="cv-bind" 
  alt="Avatar" 
/>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

OUTPUT:

View [[username : CustardUI]]'s profile on GitHub

Placeholder-Driven Toggles

Show or hide content based on whether a placeholder has been set, using placeholder-id on <cv-toggle>:

<!-- Hidden until reader sets a username -->
<cv-toggle placeholder-id="username">
  Welcome, [[username]]! Here are your personalised instructions.
</cv-toggle>
 
<!-- Visible if user has set a value OR a defaultValue exists -->
<cv-toggle placeholder-id="username*">
  Welcome, [[username]]!
</cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Attributes of <cv-placeholder>

<cv-placeholder> is the underlying custom element created by the [[ ]] syntax. You rarely need to use it directly, but it is useful when the shorthand syntax cannot express what you need. For example, when your fallback or truthy template contains a : (e.g. a full URL with ://), since the parser uses : as a structural separator and would misread it.

<!-- Fallback containing a URL — shorthand [[ ]] cannot do this -->
<cv-placeholder name="docsUrl" fallback="https://example.com/docs"></cv-placeholder>

<!-- Conditional with a URL in the if-set template -->
<cv-placeholder name="username" if-set="https://github.com/$" if-unset="(not set)"></cv-placeholder>

<!-- Same as \[[username* ? Hi, $! : ]], where it triggers on defaultValue as well -->
<cv-placeholder name="username" if-set="Hi, $!" if-unset="" include-default></cv-placeholder>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Cannot be used in HTML attribute binding. <cv-placeholder> is a DOM element and cannot be embedded inside an attribute value. For dynamic href, src, or other attributes, use the [[ ]] shorthand with class="cv-bind" instead.

Escaping Syntax

You can "escape" the placeholder syntax if you want to display the literal brackets instead of a variable. If you are using a static site generator, you may need to escape the backslashes.

• In Markdown Text: Use two backslashes: \\\[[ variable ]].
• In Code Blocks: Use one backslash: \\[[ variable ]].

Placeholder Input

<cv-placeholder-input/>

Place an editable input field directly on the page, allowing readers to set a placeholder value inline without opening the settings panel. The value updates all instances of the placeholder immediately.

For example, update your username here: . Notice that the placeholder, "\[[username]]", updates as you type, as so: [[username : ]].

<!-- Inline layout -->
%%Use the inline layout to edit placeholders directly in the text flow:%%

My username is 'outline': <cv-placeholder-input name="username" appearance="outline"></cv-placeholder-input>, 
'underline': <cv-placeholder-input name="username" appearance="underline"></cv-placeholder-input>, 
and 'ghost': <cv-placeholder-input name="username" appearance="ghost" width="auto-grow"></cv-placeholder-input>.

---

<!-- Stacked layout -->
%%Alternatively, use the stacked layout:%%
<cv-placeholder-input name="username" layout="stacked"></cv-placeholder-input>

---
 
<!-- Horizontal layout -->
%%Or the horizontal layout:%%
<cv-placeholder-input name="username" layout="horizontal" label="Username:"></cv-placeholder-input>

---

<!-- Card layout -->
%%Or the card layout, which is great for settings pages:%%
<cv-placeholder-input name="username" layout="card"></cv-placeholder-input>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Attributes of <cv-placeholder-input>

Several attributes control the appearance and behavior of the component.

Configuration

Placeholders are defined in your custardui.config.json under the placeholders key:

{
  "config": {
    "placeholders": [
      {
        "name": "username",
        "defaultValue": "JohnDoe",
        "settingsLabel": "Your GitHub Username",
        "settingsHint": "Enter your GitHub username",
        "description": "Used to personalise links and commands throughout the site.",
        "isLocal": false
      },
      {
        "name": "repo",
        "settingsLabel": "Repo Name",
        "description": "Enter your GitHub repo name here",
        "settingsHint": "Enter here",
        "isLocal": true,
        "defaultValue": "your-repository-name"
      }
    ]
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Configuration Fields

Global vs. Local Placeholders

By default, all placeholders defined in your configuration are global, and their input fields appear in the settings panel on every page of your site.

You can mark a placeholder as local to make it appear in the settings only on pages where that placeholder is actually used. This is useful for keeping the settings panel clean and focused on what's relevant to the current page.

To mark a placeholder as local, add "isLocal": true to its configuration:

{
  "config": {
    "placeholders": [
      { "name": "username", "settingsLabel": "Your Username", "isLocal": false },
      { "name": "repo", "settingsLabel": "Repository Name", "isLocal": true }
    ]
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

In this example, repo only appears in the settings panel on pages that contain [[repo]] or a <cv-placeholder-input name="repo">. On all other pages, only username is shown.

Site-Managed Placeholders

If a placeholder needs to be locked — preventing readers from changing it via the settings panel, a shared URL, or their saved preferences — mark it with siteManaged: true:

{
  "config": {
    "placeholders": [
      { "name": "institution", "defaultValue": "NUS", "siteManaged": true },
      { "name": "course", "defaultValue": "CS2103T", "siteManaged": true }
    ]
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

An adaptation can then override the value via preset.placeholders:

{
  "id": "sutd",
  "preset": {
    "placeholders": { "institution": "SUTD", "course": "50.001" }
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

A site-managed placeholder:

• Does not appear in the settings panel.
• Is not included in generated shareable URLs.
• Ignores any value stored in localStorage or supplied via URL parameters.

See Site-Managed Components in the Adaptations guide for the full picture.

Tab Group Binding

Bind a tab group to a placeholder so that switching tabs automatically updates the variable:

"tabGroups": [
  {
    "groupId": "fruit",
    "label": "Fruit Selection",
    "description": "Select your favorite fruit.",
    "isLocal": false,
    "default": "pear",
    "placeholderId": "fruit",
    "tabs": [
      {"tabId": "apple","label": "Apple", "placeholderValue": "apple"},
      {"tabId": "orange","label": "Orange", "placeholderValue": "orange"},
      {"tabId": "pear","label": "Pear", "placeholderValue": "pear"}
    ]
  }
]

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Double click a tab below to update the variable.

<cv-tabgroup group-id="fruit">
    <cv-tab tab-id="apple"> I love apples. </cv-tab>
    <cv-tab tab-id="orange"> I love oranges. </cv-tab>
    <cv-tab tab-id="pear"> I love pears. </cv-tab>
</cv-tabgroup>

\[[fruit]]

My favourite fruit is `\[[fruit]]`, and it updates automatically!

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Shareable URLs

Values are saved in the browser's localStorage and persist across page reloads and navigation. They can also be shared via the ph URL parameter — a comma-separated list of key:value pairs, each component encoded with encodeURIComponent:

https://yoursite.com/page.html?ph=username:alice,repo:my-repo

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Constructing the URL in JavaScript:

const ph = { username: 'alice', repo: 'my-repo' };
const param = Object.entries(ph)
  .map(([k, v]) => `${encodeURIComponent(k)}:${encodeURIComponent(v)}`)
  .join(',');
const url = `https://yoursite.com/page.html?ph=${param}`;

    

    Copy
    

    


    
    
    
    

    Wrap Text