Icon Repeater

Intermediate · 10 min read

Overview

The Icon Repeater lets you display a row, column, or grid of repeated icons whose count is driven by your CSV data. Instead of typing "HP: 3" on a card, you can show three heart icons. Instead of writing "Rating: 4", you can display four filled stars. Common use cases include:

• Health pips: a row of hearts representing hit points.
• Star ratings: filled stars for difficulty, quality, or power level.
• Resource costs: mana crystals, gold coins, or energy bolts showing what a card costs to play.
• Damage indicators: sword or explosion icons showing attack power.

Chitmunk offers two ways to show repeated icons:

• Icon Repeater element: a dedicated display mode on image elements that repeats an icon based on a numeric value. Gives you full control over layout, spacing, and fractional display.
• Inline icon tokens: a special [icon:name] syntax you can embed directly inside text elements and CSV data. Great for mixing icons with regular text.

Quick Start: Your First Icon Repeater

The fastest way to get repeating icons on your cards:

1. Load a CSV with a numeric column. For example, a column called "HP" with values like 1, 2, 3, 4, 5 across your card rows.
2. Drag the numeric column onto the canvas. Chitmunk creates a text element bound to that column.
3. Select the element, then find Display Mode in the properties panel. Click Icon Repeater.
4. Click "Choose Icon" and pick a heart icon from the Clip Art Browser.

That is it. The element now shows hearts instead of a number, three hearts for cards where HP is 3, five hearts where HP is 5. Use the card navigator to flip through rows and see the count change on each card.

Quick Start: Inline Icons in Text

If you want to mix icons with regular text: like "Rating: 3 stars" but with actual star icons, use inline icon tokens.

1. Open Icon Tokens from the tool strip (left edge of the canvas) and add an icon. Give it a short name like "star".
2. In your CSV data, type: Rating: [icon:star x3]
3. Or use a CSV column to drive the count: Rating: [icon:star x{{Stars}}]

When the card renders, the [icon:star x3] token is replaced with three inline star icons right inside the text flow. The icons scale to match your font size automatically.

Choosing Your Icon

When you set up an Icon Repeater element or add an icon to Icon Tokens, you choose the artwork from one of several sources:

• Clip Art Browser: search across 275,000+ icons from Iconify. Swords, shields, hearts, stars, skulls, gems, flames, you name it.
• Kenney Board Game Pack: 523 CC0 game art pieces including dice, meeples, tokens, and chips. No attribution required.
• Custom upload: upload your own SVG, PNG, or JPEG to use as the repeated icon. Great for branded or hand-drawn artwork.
• Icon Tokens: save frequently used icons with short names so you can reference them in inline tokens. The token list persists across your project.

Layout Options

The Icon Repeater supports three layout modes that control how the icons are arranged within the element's bounding box:

• Horizontal: icons flow left to right in a single row. Perfect for a row of hearts showing HP, or a line of coins showing cost.
• Vertical: icons stack top to bottom in a single column. Works well for a mana bar or a vertical resource track along the card edge.
• Grid: icons wrap into rows and columns to fill the bounding box. Ideal for larger counts like a 5-star rating system where you want a compact arrangement, or for showing 10+ resource icons in a tidy block.

The flow direction property controls the fill order within the layout. For horizontal layout, you can fill left-to-right or right-to-left. For vertical, top-to-bottom or bottom-to-top. For grid, the flow direction sets whether rows fill left-to-right or right-to-left.

Fine-Tuning

Once you have the basic layout working, the properties panel gives you precise control over the details:

• Spacing: adjust horizontal and vertical gaps between icons. Tighter spacing looks more compact; wider spacing gives each icon room to breathe. Values are in pixels.
• Alignment: control how icons align within the bounding box. Options include start, center, and end alignment for both the primary axis and the cross axis. For example, centering a row of hearts within a wider bounding box.
• Wrapping: when the icon count exceeds what fits on a single row (horizontal) or column (vertical), wrapping controls whether icons flow onto the next line or get clipped. In grid mode, wrapping is always enabled.

Fractional Icons

Sometimes your data includes fractional values, a card with 2.5 HP, or a 3.5-star rating. The Icon Repeater handles this gracefully by clipping the last icon to show a partial fill.

For example, if the count is 3.5, the repeater shows three full icons followed by a fourth icon that is clipped to show only its left half. This gives you a natural "half-heart" or "half-star" effect without needing separate half-icon artwork.

The clip direction property controls which edge the partial icon is clipped from:

• Left to right: the partial icon fills from the left edge. A 0.5 value shows the left half. This is the default and works best for horizontal layouts.
• Right to left: the partial icon fills from the right edge.
• Top to bottom: the partial icon fills from the top edge. Useful for vertical layouts.
• Bottom to top: the partial icon fills from the bottom edge. Creates a "filling up" effect.

Inline Icons in Text

Inline icon tokens let you embed icons directly inside text elements and CSV data. The syntax is straightforward:

Inline icons render at the same size as the surrounding text by default, or at the pixel size you specify after the second colon. They sit on the text baseline and flow naturally with the text, just like emoji characters.

Because the count can be driven by {{ColumnName}} template variables, each card in your deck can show a different number of icons. For example, a text element containing Cost: [icon:coin x{{Gold}}] would show "Cost:" followed by the appropriate number of coin icons for each card's Gold value.

You can mix multiple icon tokens in a single text element:

[icon:sword x{{ATK}}] Attack · [icon:shield x{{DEF}}] Defense

This displays a row of sword icons, the word "Attack", a separator, a row of shield icons, and the word "Defense", all in one text element.

Icon Repeater Properties Reference

Full reference for every property available on an Icon Repeater element:

Inline Token Syntax Reference

Every supported inline icon token variant:

Tips & Best Practices

• Keep counts under 20. Icon Repeaters are designed for quick visual communication. Beyond 20 icons, the element becomes hard to read at card scale. If you need to represent large numbers, consider using a number label alongside a smaller icon count.
• Choose icons that read well at small sizes. Simple, bold shapes like hearts, stars, circles, and diamonds are instantly recognizable even at 10-12px. Detailed icons with fine lines tend to turn into blobs when repeated at small sizes.
• Test fractional clipping with your icon. Not every icon looks good when clipped in half. Symmetrical shapes (hearts, stars, circles) clip cleanly. Asymmetrical shapes (swords, potions, characters) may need a different clip direction or may look better with fractional display turned off.
• Use Icon Tokens for inline syntax. If you plan to use inline icon syntax in your CSV data, set up icons in Icon Tokens first and give them short, memorable names. This keeps your CSV data clean and readable.
• Match icon color to your card theme. A red heart for HP, a yellow star for ratings, a blue crystal for mana, consistent color coding across your deck helps players parse information at a glance.
• Preview across all cards. Use the card navigator to step through several rows of CSV data. Make sure the icon count looks good at both the minimum and maximum values in your dataset.