Icon Repeater

Intermediate · 10 min read · By Chitmunk Team · Updated Oct 18, 2026

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: repeats an icon as many times as a number says, from a spreadsheet column or a fixed count. Add it from Icon repeater in the Add panel, or switch a text box linked to a number to Show as: Icon repeater. Gives you full control over layout, spacing, and partial icons.
• 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. Bring in a spreadsheet with a numeric column on the Data tab. For example, a column called "HP" with values like 1, 2, 3, 4, 5 across your card rows.
2. On the Design tab, click the column under From your spreadsheet in the Add panel (or drag it onto the card). Chitmunk adds a text box linked to that column.
3. Select the box, then find Show as at the top of the properties panel. Click Icon repeater.
4. Click "Choose icon" under Icon and pick a heart 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 Icons in text in the Add panel (the Icon Tokens window) and add an icon. Give it a short name like "star".
2. In a text box or a spreadsheet cell, 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 (in the Add panel): search across 275,000+ icons from Iconify. Swords, shields, hearts, stars, skulls, gems, flames, you name it.
• Board game pieces: 523 CC0 game art pieces from Kenney, including dice, meeples, tokens, and chips. No attribution required.
• Upload: use your own image file 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:

• Side gap and Row gap: the space between icons, from 0 to 100 pixels (4 to start).
• H Align and V Align: where the icons sit in the box, left, center or right and top, center or bottom. Center a row of hearts in a wider box with H Align center.
• Icon size: 8 to 200 pixels (24 to start).
• Rotation and Offset: turn each icon, or nudge it sideways or up and down.
• Wrap: when the icons do not fit on one row or column, wrapping lets them flow onto the next line instead of being clipped. It is on to start. A grid has its own Columns and Rows (5 by 2 to start).

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 Cut off from choice controls which side of the partial icon is trimmed:

• Right: the right side is trimmed, so a 0.5 value shows the left half. This is the default and works best for horizontal layouts.
• Left: the left side is trimmed.
• Bottom: the bottom is trimmed, so the icon shows from the top. Useful for vertical layouts.
• Top: the top is trimmed, so the icon fills from the bottom. 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.