Conditional Logic & Transforms
Overview
Conditional visibility and text transforms let you create smart cards that show different content based on your CSV data. Instead of building a separate design for every card variant, you design once and let expressions do the work: showing a fire icon only on fire-type cards, displaying a "RARE" badge only on high-rarity cards, or auto-formatting all card names consistently.
There are two complementary systems covered in this guide:
- Conditional Visibility: control whether an element appears on a given card based on an expression evaluated against the current CSV row.
- Text Transforms (Pipes): modify how text values are displayed using pipe syntax inside
{{Column}}templates, without altering the underlying data.
Both systems use the same {{Column Name}} reference syntax as the rest of Chitmunk's CSV binding. If you haven't set up a CSV data merge yet, read the CSV Data Merge guide first.
Conditional Visibility
Every element in Chitmunk has a Show if field in the properties panel. Leave it blank and the element always appears. Enter an expression and the element is shown only when that expression evaluates to true for the current CSV row, and hidden otherwise.
To set a condition:
- Select an element on the canvas.
- In the Properties panel, find the Show if field (under the Visibility section).
- Type an expression using
{{Column}}references and one of the operators listed below. - Browse through your CSV rows using the row navigator. The element will appear and disappear as Chitmunk evaluates your expression against each row's data.
Tip: Elements with a master: true flag are never affected by conditional visibility; they always render. Use the master toggle for elements that should appear on every card regardless of data, such as the card frame or border.
Comparison Operators
Use these operators to compare a column value against a literal value. String literals should be wrapped in single quotes. Numeric comparisons work without quotes.
| Expression | Meaning |
|---|---|
{{col}} == 'value' |
Equals (string or number) |
{{col}} != 'value' |
Not equals |
{{col}} > 5 |
Greater than (numeric) |
{{col}} < 10 |
Less than (numeric) |
{{col}} >= 5 |
Greater than or equal (numeric) |
{{col}} <= 10 |
Less than or equal (numeric) |
Comparisons are case-sensitive. {{Type}} == 'Spell' does not match a row where the Type column contains spell or SPELL.
String Operators
These operators check for patterns within string values rather than exact matches.
| Expression | Meaning |
|---|---|
{{col}} contains 'fire' |
Column value includes the substring |
{{col}} !contains 'poison' |
Column value does not include the substring |
{{col}} startsWith 'The' |
Column value begins with the string |
{{col}} endsWith 'ing' |
Column value ends with the string |
{{col}} isEmpty |
Column is blank or missing from the row |
{{col}} isNotEmpty |
Column has any non-blank value |
Tip: isEmpty and isNotEmpty are particularly useful for optional columns. If your CSV has a Subtitle column that only some cards use, you can show the subtitle element only when {{Subtitle}} isNotEmpty.
Range Operator
The between operator checks whether a numeric column value falls within an inclusive range. It is a clean alternative to combining two comparison operators.
{{col}} between 5 and 10
This is equivalent to {{col}} >= 5 AND {{col}} <= 10, but easier to read. It is well suited to tier-based styling, for example, showing a gold border only on cards with a Rarity between 4 and 6:
{{Rarity}} between 4 and 6
Boolean Logic
Combine multiple conditions using AND, OR, and NOT. Keywords are case-insensitive (and and AND both work).
| Operator | Example |
|---|---|
| AND | {{Type}} == 'Spell' AND {{Level}} > 3 |
| OR | {{Faction}} == 'Red' OR {{Faction}} == 'Blue' |
| NOT | NOT {{Status}} == 'Banned' |
Use parentheses to control evaluation order when mixing AND and OR:
({{Type}} == 'Spell' OR {{Type}} == 'Trap') AND {{Level}} > 3
Without parentheses, AND binds more tightly than OR, the same precedence rules as most programming languages. When in doubt, add parentheses to make your intent explicit.
Tip: Keep conditions as simple as possible. A boolean chain longer than two or three clauses is hard to debug, especially when you are browsing rows and trying to figure out why an element is or isn't appearing. Consider splitting complex logic across multiple elements with simpler individual conditions.
Text Transforms (Pipes)
Text transforms modify how a column value is displayed without changing your CSV data. Use the pipe character | inside a {{Column}} template to apply a transform:
| Syntax | Output |
|---|---|
{{Name|upper}} |
UPPERCASE |
{{Name|lower}} |
lowercase |
{{Name|capitalize}} |
Title Case (first letter of each word capitalized) |
{{Name|trim}} |
Leading and trailing whitespace removed |
{{Name|truncate:20}} |
Cut to 20 characters, with an ellipsis appended if truncated |
Transforms work anywhere you use a {{Column}} reference: inside a text element's content, in an image element's binding column, or in an AI prompt.
Transform Chaining
Combine multiple transforms by chaining them with additional pipe characters. Transforms execute left to right, each receiving the output of the previous transform as its input.
{{Name|trim|upper|truncate:15}}
This expression first trims whitespace from the Name value, then converts it to uppercase, then cuts it to 15 characters. Order matters: {{Name|truncate:15|upper}} would truncate first and then uppercase the truncated result, which is fine, but {{Name|upper|truncate:15}} and {{Name|truncate:15|upper}} produce the same final output since case conversion does not affect length.
Tip: A common pattern is {{Name|trim|capitalize}}; it cleans up inconsistent spacing or capitalization in your CSV without requiring you to re-edit the source data.
Fallback Values
Use the || (double pipe) operator to specify a fallback value that is displayed when a column is empty or missing from a row:
{{Description || 'No description available'}}
If the Description column for the current row is blank, the text No description available is rendered instead. If Description has a value, that value is used normally.
Fallbacks work alongside transforms. The transform is applied to the resolved value, whether that value came from the column or the fallback:
{{Name || 'Unknown'|upper}}
This renders the Name value in uppercase, or UNKNOWN if Name is empty. The |upper transform applies after the fallback is resolved.
Tip: Fallback values are especially useful for optional CSV columns. If some rows have a Subtype column and others don't, use {{Subtype || ''}} to silently output nothing instead of displaying a literal {{Subtype}} placeholder on cards where the column is missing.
Practical Examples
Here are common patterns you can adapt for your own card designs.
Show a fire icon only on fire-type cards:
Set the Show if field on your fire icon element to: {{Element}} == 'Fire'
Show a "RARE" badge on high-rarity cards:
Set Show if to: {{Rarity}} > 3
Show different art frames by faction:
Create a separate image element for each faction's frame art. Set the Show if on the Red frame to {{Faction}} == 'Red', the Blue frame to {{Faction}} == 'Blue', and so on. Only one frame will render per card.
Auto-uppercase all card names:
In your card name text element, use {{Name|upper}} as the text content instead of plain {{Name}}.
Truncate long descriptions to fit a fixed text area:
Use {{Description|truncate:80}} to cap descriptions at 80 characters. You can also use the Auto Shrink font option in the text element properties to automatically reduce font size instead of truncating, choose whichever fits your design.
Show a special badge only on cards of specific types:
({{Type}} == 'Spell' OR {{Type}} == 'Trap') AND {{Level}} >= 5
Hide an element when an optional column is blank:
{{FlavorText}} isNotEmpty
Tips & Best Practices
- Test as you go. Use the bottom navigator bar to browse through cards while editing. You will immediately see which rows cause an element to appear or disappear, making it easy to catch mistakes in your expressions.
- Use master elements for always-visible content. Decorative borders, the card frame, and any element that should never be hidden should have the master toggle enabled. Master elements are never evaluated against conditional expressions.
- Keep conditions simple. Complex boolean chains are hard to debug, especially with large CSVs. If you find yourself writing a four-clause AND/OR expression, consider whether you can restructure your CSV data (for example, adding a computed column in your spreadsheet) to make the condition simpler.
- Use fallback values for optional columns. If your CSV has columns that only some rows fill in, use
{{Column || ''}}or{{Column || 'default text'}}to prevent placeholder text from appearing on cards where the column is absent. - Transforms do not affect visibility expressions. The Show if field uses raw column values for comparisons, pipe transforms in the Show if field are not supported. Use transforms only inside text content templates.
- Duplicate, don't rebuild. When creating per-faction or per-type variants, duplicate an existing element and change only the Show if condition and the image source. This keeps your element stack organized and avoids re-entering position, size, and style settings.