Data files & mappings

#Data files (Datasets)

A dataset is a file containing data that will be inserted into your design. SXL Studio supports two formats: JSON and CSV.

#JSON format

A JSON dataset is an array of objects. Each object represents one data row.

[
  {
    "name": "Nike Sneakers",
    "price": "$129.90",
    "image": "https://cdn.example.com/nike.png",
    "inStock": true
  },
  {
    "name": "Adidas T-Shirt",
    "price": "$34.90",
    "image": "https://cdn.example.com/adidas.png",
    "inStock": false
  }
]

Rules:

• The root must be an array [ ]. If you pass a single object { }, the plugin wraps it in an array automatically.
• Object keys can be any strings. Nesting is supported via dot-path: user.name, meta.tags.
• Values: strings, numbers, booleans, nested objects.

Nested objects

When a key's value is an object, the plugin resolves the text value by priority:

1. Current locale key (ru, en)
2. default
3. value
4. text
5. title
6. name

If none of these keys are found, the value is serialized as a JSON string.

[
  {
    "title": {
      "ru": "Главная",
      "en": "Home"
    },
    "price": {
      "value": 1299,
      "currency": "USD"
    }
  }
]

#CSV format

A CSV file is a table with headers in the first row. The delimiter is a comma.

name,price,image,inStock
"Nike Sneakers","$129.90",https://cdn.example.com/nike.png,true
"Adidas T-Shirt","$34.90",https://cdn.example.com/adidas.png,false
"Puma Backpack","$59.90",https://cdn.example.com/puma.png,true

CSV rules:

• First row — headers (column names).
• Minimum 2 rows (header + at least one data row).
• Wrap values containing commas, line breaks, or quotes in double quotes: "Text, with comma".
• Escape double quotes inside values by doubling: "He said ""hello""".
• Line breaks inside quoted values do not split the row.
• Duplicate column names get suffixes: name, name_2, name_3.

Auto type parsing

Numeric strings are automatically converted to numbers, except:

• strings with leading zeros (001, 007) — remain strings;
• empty strings.

Boolean strings true/false are converted to booleans.

#CSV editing modes

The plugin offers two editing modes for CSV files:

In Table mode you can:

• rename columns (double-click the header);
• add rows — the Add Row button at the bottom of the table;
• add columns — the + icon on the right side of the header;
• drag columns to reorder;
• click a header to sort the column (ASC ↔ DESC);
• filter rows across all cells — the Search rows… input in the toolbar;
• select rows via the checkbox column — switches the toolbar into bulk-action mode:
  • Duplicate — insert clones of the selected rows right after the originals;
  • Delete (or the Delete / Backspace key) — remove the selected rows;
• Paste — paste CSV from the clipboard. Columns not yet present in the table are added automatically;
• Copy / Copy all — copy the selected rows (or all rows) to the clipboard as CSV;
• empty rows and columns are automatically removed on save.

#Asset files

Assets are images uploaded to the plugin. Supported formats: PNG, JPG, WebP, SVG. WebP and SVG are automatically converted to PNG on upload.

Assets can be used as values for image substitution by key.

#File organization

• File names can include a path with /: entering cards/products creates a products file inside a cards folder.
• Mapping files are saved with the .map.json extension.
• You can also create folders using the Folder button in the toolbar.

#Mappings

A mapping is a set of rules describing which data goes into which layers. A single mapping can contain an unlimited number of fields.

#Field structure

Each mapping field consists of three required parameters and several optional ones:

#Key Expression — syntax

A Key Expression defines which value from a dataset row is inserted into a layer. The core syntax is a key name in square brackets:

[key]

Examples:

Concatenation

Multiple [keys] in one expression are concatenated:

[city], [country]

Result: New York, USA

Removal modifier

Use the - separator (space-dash-space) to specify a substring to remove from the result:

[status] - prefix_

If status = "prefix_active", result: active.

The special modifier *- removes everything up to the last hyphen:

[code] - *-

If code = "btn-primary-large", result: large.

#Target Layer — layer matching

The plugin matches layers by two criteria:

1. Layer name (node.name) — exact match;
2. Text content (characters) — for TEXT nodes, exact match.

#Fill Strategy

Determines the order in which dataset rows are distributed among multiple instances of the target layer:

When rows run out, the counter wraps back to the beginning.

#Field groups

Fields can be organized into groups. A group defines how multiple cards/blocks share dataset rows.

Group Fill Mode — row distribution between groups:

Example:

Given 3 cards and 6 data rows:

• same: card 1 → rows 1,2; card 2 → rows 1,2; card 3 → rows 1,2.
• global: card 1 → rows 1,2; card 2 → rows 3,4; card 3 → rows 5,6.

#Mapping settings

Default dataset

Select the dataset that all mapping fields will use by default. Individual fields can override the dataset.

Bind component

Bind the mapping to a specific component (by key). During instance generation, the plugin verifies that the template is an instance of this exact component.

Auto-hide unused

When enabled, layers that have no matching data (empty string, null, missing key) are automatically hidden (visibility: false). This is convenient for optional elements: badges, promo banners, extra fields.

Auto-fill

Automatic field generation from the selected dataset's keys. The plugin creates one field for each top-level key.

#Value directives

Beyond plain text and image URLs, cell values can contain directives — special commands for controlling Figma nodes.

#@prop — component property control

@prop:PropertyName=value

Multiple properties with ;:

@prop:HasBadge=true;Size=Large;Label=New

Value types:

If a property value contains ;, escape it: \;

@prop:Description=Text\; with semicolon

#@hide — hide a layer

@hide

Sets visible = false on the target layer.

#@node:visible — visibility control

@node:visible=false
@node:visible=true

Similar to @hide, but allows explicitly enabling visibility.

#Images

When a value is an image URL (http/https), the plugin automatically downloads it and applies it as a fill for the target layer.

{ "avatar": "https://example.com/photo.jpg" }

#Boolean values for Instances

When the target layer is an INSTANCE and the value is true or false (boolean), the plugin controls the visibility of that instance:

• true → visible
• false → hidden

#Full example: product cards

#Dataset products.json

[
  {
    "title": "Nike Air Max Sneakers",
    "price": "$129.90",
    "description": "Lightweight running and everyday sneakers",
    "image": "https://cdn.example.com/nike-air-max.png",
    "badge": "@prop:Visible=true;Label=Best Seller",
    "rating": "4.8"
  },
  {
    "title": "Adidas Originals T-Shirt",
    "price": "$34.90",
    "description": "Classic cotton t-shirt",
    "image": "https://cdn.example.com/adidas-originals.png",
    "badge": "@prop:Visible=false",
    "rating": "4.5"
  },
  {
    "title": "Puma Phase Backpack",
    "price": "$59.90",
    "description": "Spacious backpack for the city",
    "image": "https://cdn.example.com/puma-phase.png",
    "badge": "@prop:Visible=true;Label=New Arrival",
    "rating": "4.7"
  }
]

#Mapping products.map.json

Settings:

• Dataset: products.json
• Auto-hide unused: ✅
• Group Fill Mode: Sequential

#Figma layer structure

ProductCard (Component)
├── product-image (Rectangle)
├── badge (Instance: BadgeComponent)
├── product-title (Text)
├── product-price (Text)
├── product-description (Text)
└── product-rating (Text)

#Result

Select 3 cards → Apply Data:

• Card 1: Nike Air Max, $129.90, with "Best Seller" badge
• Card 2: Adidas Originals, $34.90, badge hidden
• Card 3: Puma Phase, $59.90, with "New Arrival" badge

#Related pages

• General overview: Database overview
• Apply and generate mechanics: Apply & Generate