How block tables work

This takes about 5 minutes to read. By the end, you’ll know how a document table becomes a Commerce block (or a Content block) on the storefront, and how the block name row, key-value settings, and optional full-width content rows work together.

Example: a block table in your document

In Commerce Storefront, you add a block by adding a table to the page. Use the table below as the reference; the list under it names each part.

commerce-company-credit
showHistory	true
Optional: in some blocks, a merged full-width row is where the visible page content goes when it does not fit in a small value cell. Not every block uses this row.

Read the table from top to bottom:

• The first row (full width, shaded) is the block nameThe first row in a block table. It usually contains a single `kebab-case` block identifier (for example, `commerce-cart` or `targeted-block`) that tells the system which block to render. row. It is usually a single kebab-case name such as commerce-cart or targeted-block. The storefront uses that name to choose the right block implementation. In some editors, the name may appear in the first cell with the second cell left empty, but the rule is the same: one clear block identifier.
• Rows with two cells are key-valueA two-column table row in a block table. The first cell is a setting name (a key) and the second cell is the value, such as `true`, `10`, or a text label. settings: a property name in the first column and a value in the second. Many options are optional and use safe defaults if you leave them out. Each block’s documentation lists the valid keys, allowed values, and which keys (if any) are required.
• A row with one cell spanning the full width is a merged full-width rowA table row where one cell spans the full table width, so you can add rich page content in one large cell. Some blocks (like `targeted-block`) use this for inline content or layout when a separate fragment document is not used. when the cell holds block content, not a second key-value line. The italic row in the example shows that option. For some blocks you can point to another document with a fragment path in the block settings instead of inlining the content. See the next section and Personalization setup.

Where is my block?

If a block does not appear on the page when previewed, the most common problem is a block name that does not match the spelling in the block reference. If a block is wrong or empty, check the full-width and fragment content rules for that block in the reference, or use Personalization setup for targeted-block.

What is a fragment?

In a targeted-block table, the fragment setting is a fragment pathAn optional `TargetedBlock` setting that points to a separate content document. When set, the block loads content from that document; when omitted, the content is authored in the last merged full-width row of the `targeted-block` table.: a separate document path the storefront can load to supply the content for the block, instead of writing that content in the same table. This is not the same as a URL hash fragment (the part of a link after #).

For targeted-block authoring, see Personalization setup.

Start authoring a block in your document

1. In Document Authoring, add a new table, set the name row to the block you want in kebab-case, and add the key-value rows the block’s documentation requires or recommends.

2. Preview the page, then publish when it looks right. For a full end-to-end example (metadata, cart block, section styling), work through Your first page.

Related resources

• Using Content and Commerce blocks - A broad overview of blocks, drop-ins, and authoring.
• Your first page - A full walkthrough that includes a commerce-cart table example.
• Personalization setup - A practical guide for the targeted-block case, including fragment and the last merged full-width content row.
• TargetedBlock (developer reference) - Technical details of how a TargetedBlock is resolved, when you need deeper context than day-to-day authoring.