Shelf logic is a written instruction that defines which products appear on each shelf and how they're arranged. It uses a bracketed statement in your question text to specify product placement.

For most shelf arrangements, you can use the shelf editor to position products visually. Shelf logic is especially useful when you want to show different shelf arrangements based on respondents' earlier answers.

Learn more about Shelf Test in our Lighthouse Academy course!

In This Article

• Where Your Arrangement Lives
• Writing Shelf Logic by Hand
• Shelf Logic Alignment Commands
• Multiple Facings
• Club Store Logic
• Custom Shelf Configurations
• Possible Errors

Where Your Arrangement Lives

When you arrange products in the shelf editor, your layout is saved with the question's shelves. You can build the arrangement visually or use Show logic text to edit it in bracketed notation. In either case, the editor stores the arrangement without writing anything into your question text.

When a respondent reaches the question, the shelf arrangement comes from the first applicable source:

1. A matching conditional shelf statement in the question text. If the statement includes an if condition that matches the respondent's earlier answer, its arrangement takes priority.

2. The arrangement in the shelf editor. If no conditional statement applies, the saved editor arrangement is used, provided at least one product has been placed on a shelf.

3. A plain shelf statement in the question text. If every shelf in the editor is empty, an unconditional statement can define the arrangement.

4. Automatic placement. If every shelf in the editor is empty and no shelf statement applies, products are placed automatically.

Writing Shelf Logic by Hand

Editing shelf logic in the question text field

Type shelf logic into the Question text field. You reference products by their position in your product list.

1. Type [ followed by an alignment command, such as shelf.
2. Type { to open a shelf, then the numbers of the products on that shelf, separated by commas.
3. Type } to close the shelf. To add another shelf, type a comma and open the next one with {.
4. To make the statement conditional, type if and your condition after the last shelf.
5. Type ] to close the statement.

For example:[shelf {1,2,3},{4,5,6}]. This places products 1–3 on the first shelf, 4–6 on the second.

To make the arrangement conditional: [shelf-left {1,2},{3,4} if Q5A1]. This arrangement applies only to respondents who selected the first answer to Question 5. Products are aligned to the left.

Showing different arrangements to different respondents

You can create multiple conditional shelf statements, each targeting a different group of respondents.

For example:

• [shelf-left {1,2},{3,4} if Q5A1]
• [shelf-right {3,4},{1,2} if Q5A2]

Respondents who selected answer 1 in Question 5 see the first arrangement, with products aligned to the left. Those who selected answer 2 see the second arrangement, with products aligned to the right.

If neither condition applies, the question uses the next available placement source: the shelf editor, a plain shelf statement, or automatic placement.

Editing shelf logic in the shelf editor

You can also view and edit shelf logic directly in the shelf editor.

1. Click Arrange to open the shelf editor and turn on Show logic text in the sidebar.
2. The product card is replaced with a text box containing the current shelf arrangement in bracketed notation.
3. Edit the statement to change which products appear on each shelf.
4. Click Apply to update the arrangement in the shelf editor, or Revert to discard your unapplied changes.

When you click Apply, the editor converts your written statement into a visual shelf arrangement. These changes are saved with the question's shelves and can be undone in a single step.

⚠️ Note: Show logic text is unavailable in the club store pallet structure view.

Counting shelves

Shelves are counted from top to bottom within each section, then from one section to the next.

For predictable placement, include one set of braces for each shelf in your question.

• If you provide fewer sets of braces than the question has shelves, the remaining shelves are automatically left empty. This doesn't produce an error.
• If you provide too many, the extra shelves and the products assigned to them are ignored. The excess shelves can trigger a validation error.

Leaving a shelf empty

Use empty braces {} when you want to leave a particular shelf without products.

For example:

[shelf {1,2},{},{3}]

This places products 1 and 2 on the first shelf, leaves the second shelf empty, and places product 3 on the third.

Using empty braces helps you maintain the intended shelf order, especially when your arrangement contains several shelves or sections.

💡 Tip: To show different respondents different shelves, write one conditional statement per branch. Only one shelf statement may apply to a respondent at a time.

Shelf Logic Alignment Commands

Alignment decides how products are spread across each shelf. In the shelf editor, it's the segmented control at the top of the canvas; in written logic, it's the command you open with.

⚠️ Note: Alignment applies to the whole question, not to a single shelf, so a Shelf Test question uses only one shelf command. A misspelled command isn't recognized: It stays in your question text as plain text and places nothing.

Multiple Facings

A facing represents one visible instance of a product on a shelf. To display a product multiple times, repeat its product number in the shelf statement.

For example:[shelf {1,1}]. This gives product 1 two facings on the same shelf.

In the shelf editor, you do the same thing by placing the product twice, or by setting its Fill style and letting Auto-arrange do it.

Club Store Logic

Club store pallets number their shelves differently—products are assigned from left to right across the top level, then across the levels below it. The number of {braces} a club question needs depends on the pallet preset you chose.

See Club Store Shelves Reference for brace counts and how club products are set up.

Custom Shelf Configurations

The [[shelfconfig]] marker has been retired. You set shelf heights, hanging shelves, and section widths directly in the shelf editor for every store and fixture, including club store pallets, which open a structure view for the same purpose.

If an existing question contains [[shelfconfig]], the marker is removed from the question text and any translations of that question. Pallet questions that relied on the marker render with the fixture's standard bottom spacing instead.

See How to Arrange Products on the Shelf.

Possible Errors

The shelf editor and written shelf logic have different validation behaviors. Some issues appear while you're building the shelf; others become visible when you preview the question.

Errors in the shelf editor

• Incorrect number of shelves. The arrangement contains too few or too many shelves for the selected store and shelf type.
• Shelf height below 4 inches. Affected shelves are highlighted in red.
• Total shelving height below the store's minimum. The editor displays an Increase to N" button to correct the height.
• Unsupported hanging shelves. A hanging shelf has been added to a store or fixture that doesn't support one.

Errors when writing shelf logic by hand

Some problems with written shelf logic can be caught during editing, while placement and rendering errors are reported in Preview.

• Incorrect number of shelves. If your statement contains more sets of braces than the question has shelves, the extra shelves and their products are ignored. This can trigger an error during editing or in Preview. If there are fewer sets of braces, the remaining shelves are left empty without raising an error.
• Products that don't physically fit. If the total width of the products exceeds the available shelf space, Preview displays a spacing error. To resolve it, widen the section in the shelf editor or reduce the product sizes in their Product Cards.
• Products missing from the arrangement. If a product in your list isn't assigned to any shelf, Preview can flag the missing product. Check that all products you intend to display are included in your shelf statement.

Related Articles

• How to Arrange Products on the Shelf
• Club Store Shelves Reference
• How to Bulk Upload Shelf Test Assets
• How to Program a Shelf Test