---
source: https://carbone.io/documentation/design/template-formats/svg.html
title: "SVG Templates | Generate PNG and PDF from JSON | Carbone"
description: "Generate SVG images, PNG and PDF files from SVG templates and JSON with the Carbone API. Passes, charts, product cards and social images follow your data."
generated_at: "2026-11-11"
---
# SVG templates
Design an image in Illustrator, add Carbone tags, and generate it from JSON data as an SVG, a PNG or a PDF.
COMMUNITY FEATURE Available for:
✓ Carbone Cloud
✓ Carbone On-premise
✓ Embedded Carbone JS v5.0+
Any SVG file can be a template. Write Carbone tags in its text and attributes, and send your JSON data to the API. You get back an SVG, or a PNG, JPG, WebP or PDF drawn by Chromium, for event passes, KPI cards, charts, product cards and social images.
## Basic
Write a tag in a text element to insert a value from the JSON data. In `{d.attendee.firstName}`, `d` is the root of the data and `attendee.firstName` is the path to the value. The value takes the style of its text: font, size, color and letter spacing.
**Data** ([basic-data.json](/file/svg/basic-data.json)):
```json
{
"event": {
"name": "Lumen Summit",
"dates": "March 18-19, 2026",
"venue": "Pier 27",
"city": "San Francisco"
},
"attendee": {
"id": "LS26-0418",
"firstName": "Maya",
"lastName": "Okafor",
"jobTitle": "Head of Operations",
"company": "Brightline Logistics",
"role": "Speaker",
"access": "All days",
"zone": "Hall A"
}
}
```
**Template** ([basic-template.svg](/file/svg/basic-template.svg)):
```svg
```
**Result** ([basic-report.svg](/file/svg/basic-report.svg)):
- Type the tags in Illustrator and export the artboard as SVG. The settings that keep the tags readable are in [Export from Illustrator](#export-from-illustrator).
- Use `:upperCase` instead of All Caps: Illustrator exports the capital letters, and `{D.ATTENDEE.ROLE}` is not a tag.
- SVG text does not wrap. Leave room for the longest value, like a long last name.
Learn more about [tags](/documentation/design/substitutions/the-basics.md).
## Attributes
Tags work in attributes too, so the data can change a color, a size or a position. In this card, the growth badge turns red when the growth is negative: `fill="{d.growth:ifLT(0):show('#df1b41'):elseShow('#16a34a')}"`.
**Data** ([attributes-data.json](/file/svg/attributes-data.json)):
```json
{
"period": "Fiscal year 2026",
"previousPeriod": "FY 2025",
"revenue": 48200000,
"target": 56000000,
"growth": 18.4,
"grossMargin": 0.72,
"retention": 0.94
}
```
**Template** ([attributes-template.svg](/file/svg/attributes-template.svg)):
```svg
```
**Result** ([attributes-report.svg](/file/svg/attributes-report.svg)):
- Each ring is a dashed circle, and the data sets the length of the dash: `stroke-dasharray="{d.grossMargin:mul(201.06)} 201.06"`. 201.06 is the length of the circle.
- With `"lang": "en-us"`, `{d.revenue:div(1000000):formatC(1)}M` prints $48.2M.
- A path that starts with a dot reads a value of the same object: `{d.revenue:div(.target)}` divides the revenue by the target.
- Write the tags of the attributes in a code editor, after the export. Illustrator removes them when it opens the SVG, so keep the Illustrator file as the source of the design.
Learn more about [math formatters](/documentation/design/computation/simple-mathematics.md), [currencies](/documentation/design/formatters/currency.md) and [inline conditions](/documentation/design/conditions/inline-conditions.md).
## Loops
A loop repeats an element for each item of an array, like the bars of this chart:
1. In Illustrator, group the bar with its value and its label (Object > Group).
2. Duplicate the group, and write `[i+1]` in its tags, like `{d.quarters[i+1].label}`.
Carbone repeats the first group for each quarter and removes the second one.
**Data** ([loops-data.json](/file/svg/loops-data.json)):
```json
{
"title": "Revenue by quarter",
"subtitle": "Fiscal year 2026, in USD",
"scaleMax": 18000000,
"quarters": [
{ "label": "Q1", "revenue": 9800000 },
{ "label": "Q2", "revenue": 11400000 },
{ "label": "Q3", "revenue": 12100000 },
{ "label": "Q4", "revenue": 14900000 }
]
}
```
**Template** ([loops-template.svg](/file/svg/loops-template.svg)):
```svg
```
**Result** ([loops-report.svg](/file/svg/loops-report.svg)):
- **Place each bar**: every copy starts at the position of the first group. `translate({d.quarters[i].label:print(.i):mul(130)} 0)` moves each bar 130 units to the right of the previous one. `.i` is the number of the item: 0, 1, 2...
- **Size each bar**: `{d.quarters[i].revenue:div(..scaleMax):mul(180)}` gives each bar a height between 0 and 180, in proportion to its revenue. `..scaleMax` reads `scaleMax` in the parent object.
- **Show a total**: `{d.quarters[].revenue:aggSum}` sums the revenue of all quarters.
Learn more about [loops](/documentation/design/repetitions/with-arrays.md), [the loop index](/documentation/design/repetitions/with-arrays.md#access-the-loop-iterator-value) and [aggregators](/documentation/design/computation/aggregation.md).
## Conditions
Conditions remove or switch elements, depending on the data:
- **Conditional blocks** remove everything between `:showBegin` and `:showEnd`. Write them around a group, between two elements: `{d.product.onSale:ifEQ(true):showBegin}` and `{d.product.onSale:showEnd}` remove the Save badge when the product is not on sale.
- **Inline conditions** print one value or another, in a text or an attribute: the color of the dot and the delivery time follow the stock.
**Data** ([conditions-data.json](/file/svg/conditions-data.json)):
```json
{
"product": {
"name": "Aurora One",
"tagline": "Big sound. Small footprint.",
"price": 249,
"saving": 50,
"isNew": true,
"onSale": false,
"stock": 0
}
}
```
**Template** ([conditions-template.svg](/file/svg/conditions-template.svg)):
```svg
```
**Result** ([conditions-report.svg](/file/svg/conditions-report.svg)):
To hide an element without removing it, print its `display` attribute: `display="{d.product.stock:ifLT(5):show('inline'):elseShow('none')}"`.
Learn more about [conditional blocks](/documentation/design/conditions/conditional-blocks.md) and [inline conditions](/documentation/design/conditions/inline-conditions.md).
## Images
Write a tag in the `href` of an image to insert a picture from the data, given as a public URL or a Base64 data URI, like the logo. In Illustrator, place any picture and export with **Images: Link**: the file name goes in the `href`, and you replace it with the tag, `xlink:href="{d.brand.logo}"`.
**Data** ([images-data.json](/file/svg/images-data.json)):
```json
{
"brand": {
"name": "Aurora",
"logo": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0MCA0MCI+PGRlZnM+PGxpbmVhckdyYWRpZW50IGlkPSJnIiB4Mj0iMSIgeTI9IjEiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzlhOTRmZiIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iI2ZmNGQ4ZCIvPjwvbGluZWFyR3JhZGllbnQ+PC9kZWZzPjxyZWN0IHdpZHRoPSI0MCIgaGVpZ2h0PSI0MCIgcng9IjExIiBmaWxsPSJ1cmwoI2cpIi8+PGNpcmNsZSBjeD0iMjAiIGN5PSIyMCIgcj0iOCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjZmZmIiBzdHJva2Utd2lkdGg9IjMiLz48L3N2Zz4="
},
"event": {
"type": "Live launch",
"title": "Hear it first.",
"date": "2026-12-08",
"time": "6:00 PM CET",
"url": "aurora.example/live"
}
}
```
**Template** ([images-template.svg](/file/svg/images-template.svg)):
```svg
```
**Result** ([images-report.svg](/file/svg/images-report.svg)):
Download: [images-card.jpg](/file/svg/images-card.jpg)
Carbone downloads the pictures given as URLs when it converts the SVG to an image or a PDF. To display the SVG itself in a browser, give the pictures as data URIs.
See [Convert SVG to PNG or PDF](#convert-svg-to-png-or-pdf) to get `card.jpg`.
## Update shapes
`:svgUpdate` sets an attribute of the shapes whose `id` is in the data, with no tag in the shapes. It suits drawings with many parts, like product configurators, maps, floor plans and seat maps. In Illustrator, name the shapes or groups in the Layers panel and export with **Object IDs: Layer Names**: the names become ids.
`{d.parts[].color:svgUpdate('stroke', .id)}` sets the `stroke` of the element whose id is the `id` of each part, and of its direct children. Write the tag in a comment, anywhere in the SVG.
**Data** ([shapes-data.json](/file/svg/shapes-data.json)):
```json
{
"brand": "Velora",
"model": "City 3",
"finish": "Coral, gum wall tires",
"price": 1290,
"monthly": 107.5,
"parts": [
{ "id": "frame", "color": "#ff5a4e" },
{ "id": "rims", "color": "#1f2329" },
{ "id": "tires", "color": "#b88a5e" }
]
}
```
**Template** ([shapes-template.svg](/file/svg/shapes-template.svg)):
```svg
```
**Result** ([shapes-report.svg](/file/svg/shapes-report.svg)):
- Only the basic shapes are updated: `rect`, `circle`, `ellipse`, `line`, `polyline`, `polygon` and `path`. A group passes the attribute to its direct children.
- A third parameter changes the selection: `'id'` updates only the shape with this id, `'id *'` all the shapes inside the group.
- `:svgSelectiveUpdate` selects the shapes from the data instead: `{d.rooms[status='busy'].id:svgSelectiveUpdate('fill', '#fdecef')}` fills the busy rooms of a floor plan.
- Export with **Styling: Presentation Attributes**. With Internal CSS, the colors of the CSS classes win over the attributes set by `:svgUpdate`.
## Export from Illustrator
Choose File > Export > Export As, select SVG, check **Use Artboards**, then set the SVG options:
| Option | Value | Why |
| --- | --- | --- |
| Styling | Presentation Attributes | Each element keeps its own colors, and `:svgUpdate` can change them. |
| Font | SVG | Text stays text. Convert To Outlines turns the tags into paths. |
| Images | Link | The file name of a placed picture goes in the `href`, ready for a tag. Use Embed for fixed pictures. |
| Object IDs | Layer Names | The names of the Layers panel become ids, for `:svgUpdate`. |
| Minify | Off | One element per line, easier to edit. |
| Responsive | Off | Keeps the `width` and `height` of the artboard. |
Then type the tags with these rules:
- Use point text: click with the Type tool, do not drag a text box. Illustrator exports a text box line by line, at fixed positions.
- Set **Kerning** to 0 in the Character panel. With Auto or Optical kerning, Illustrator splits the tags into several `tspan` elements: Carbone joins a split tag, but the next `tspan` keeps its position and the text overlaps.
- Keep one style per tag. A change of font, size or color in a tag starts a new `tspan`.
- Illustrator exports centered and right-aligned text at the position of its first character. Add `text-anchor="middle"` or `text-anchor="end"` with the x of the center or of the right edge, like `transform="translate(560 92)" text-anchor="end"` for the price.
## Best practices
- **Size**: keep `width`, `height` and `viewBox` on the `svg` element: the PNG and the PDF take this size. For a sharp PNG, convert with `Scale: 2`: a 600 x 315 SVG gives a 1200 x 630 image.
- **Fonts**: set the fonts once, on the `svg` element, with fallbacks, like `font-family="Helvetica Neue, Inter, Arial, sans-serif"`. The converter uses the first font of the list that it has. A Google font imported in a `