Configuration
Every option has two spellings that mean the same thing: an attribute on the script tag, and a property passed to Comments.init.
All options
| Attribute | Option | Values | What it does |
|---|---|---|---|
data-key | key | sl_embed_… | Identifies your site. Required. |
data-layout | layout | bar · button · floating | A bar across the top of the page, or a button in a corner that opens into a pill. Default bar. |
data-placement | placement | top-right · top-left · bottom-right · bottom-left | Which corner the button sits in. Default bottom-right. The bar ignores it. |
data-page-params | pageParams | names, or * | Which query parameters make a different page. Default: none. |
data-snapshots | snapshots | off · false | Turns off the picture of the viewport kept with each comment. Default: on. |
data-project-id | projectId | UUID | The identifier snippets used before keys existed. Still works. |
data-key / key
The one thing a customer pastes. The key says which site this is and lets the script check that the account it belongs to may embed. It is meant to be public: it ships in your HTML, and it grants nothing by itself. Reading and writing comments still happens as the visitor's own session, under the database's row-level security.
Get one, label it and revoke it under API Key in the dashboard. A key works on one domain and its subdomains; details in Embed keys and domains.
data-layout / layout
Bar is a 44 px strip fixed to the top of the page. It is the default for a script install because the script is a guest on a finished site, and a floating control would sit on top of whatever the designer put in that corner, which is usually a chat launcher or a cookie notice. The bar takes its space rather than borrowing it:
<html>gets a custom property,--sl-inset-top: 44px, which your own CSS may read.<body>gets 44 px of extra top padding. Padding rather than margin, so your background still paints behind the bar.- Every
position: fixedorposition: stickyelement with a pixeltopis shifted down by 44 px. Elements with a percentage orcalc()top, or anchored to both top and bottom, are left alone. Headers added to the page later are caught by a mutation observer. - On screens narrower than 640 px the bar is not shown and all of this is undone. It is reapplied if the window grows again.
Any value other than button or floating, including no attribute at all, means bar.
Button is one round button in a corner, with the SharedLayers mark in grey. It takes no space from the page. A click opens it into the same pill the Chrome extension shows: layer, comment, filters, side panel and sign-in, with the mark, now green, at the end nearest the corner. Clicking the mark again, or pressing Alt+H (⌥H on a Mac), folds it back. Choose it when your page has a header the bar ends up covering, or when a strip along the top would break the design being reviewed.
- Each visitor's choice is remembered on your domain, so a reviewer who opened it finds it open on the next page.
- Folding hides the controls, not the comments: pins stay on the page and can still be opened. For a signed-in reader the folded button shows the number of unread comments.
- Anything that needs the controls opens them: Alt+C to start a comment, or a reply that asks a visitor for their name first.
- Sign in, filters and the layer menu open away from the edge, so up from a bottom corner and down from a top one.
<script async
src="https://sharedlayers.com/comments.umd.js"
data-key="sl_embed_…"
data-layout="button">
</script>
Floating is the same pill, already open on a visitor's first view. It folds into the button the same way. Installs that used floating before the button existed keep working unchanged, and can now be folded.
data-placement / placement
Which corner the button and its pill sit in, 20 px from both edges. Pick the corner your own interface leaves free: a chat launcher usually has bottom right, a cookie notice bottom left, and a top corner sits over your header. The pill opens along the edge from its corner, and its menus open towards the middle of the window.
The words can come in either order, and a space works in place of the dash: "left top" is top-left. Anything else is bottom-right. The bar ignores this option.
<script async
src="https://sharedlayers.com/comments.umd.js"
data-key="sl_embed_…"
data-layout="button"
data-placement="top-left">
</script>
The snippet builder on Install the script writes this tag for you: pick the layout and the corner, paste your key, and copy.
data-page-params / pageParams
Comments are kept per page, and by default a page is its path. /pricing and /pricing?tab=annual&utm_source=x are the same page and show the same comments.
The hash is part of the page only when it is a route: an app that routes by hash, with addresses like /app/#/docs or /app/#!/docs, gets each route as its own page, so #/docs and #/settings keep their own comments. #/ is the same page as no hash at all, and #/docs/ the same as #/docs. A hash that does not start with /, such as /pricing#plans, points to a place on the page and is ignored. Parameters inside the route (#/docs?tab=2) follow the same rule as the ones in the address: only those you name below count.
Some sites route by a query parameter instead: ?page=/inner, ?p=123, ?product=shoe. Name those parameters and they become part of the page's identity:
<!-- ?page=/inner and ?page=/other are different pages, -->
<!-- and ?page=/inner&utm=x is the same page as ?page=/inner -->
<script … data-page-params="page"></script>
<!-- two parameters -->
<script … data-page-params="category, product"></script>
<!-- every parameter counts -->
<script … data-page-params="*"></script>
Named parameters are sorted by name before they join the key, so ?a=1&b=2 and ?b=2&a=1 are one page. Parameters you did not name are ignored even when present.
Changing this setting moves comments. A comment left on /shop?product=shoe while the default was in force is filed under /shop. After you name product, it stays on /shop, which no longer matches the page it was left on. Decide before people start commenting, or accept that older comments will appear on the bare path.
The hostname is not part of the page: it is the page's address. www.acme.com and acme.com are one address. app.acme.com and staging.acme.com are different addresses, each with its own comments and layers, though one key covers both.
data-snapshots / snapshots
When someone leaves a comment, the script renders a picture of what they were looking at and stores it with the comment. A reviewer reading the comment later can open the picture, which is what makes "the button here is misaligned" still make sense after the page has changed. The picture is:
- The viewport only, not the whole page, as the commenter saw it.
- Rendered in the browser from the DOM, at most 1280 px wide, as WebP with a JPEG fallback.
- Taken in the background after the comment is saved, with an 8 second budget. If it does not finish, the comment simply has no picture.
- Blank where the page shows cross-origin images or iframes, because the browser will not let a script read those pixels. A video from another origin shows its poster, or nothing. Same-origin iframes are painted.
- Uploaded to SharedLayers storage and shown only through short-lived signed links to people who can see the comment.
Turn it off when your screens carry personal data that should not leave the browser, or when the render is too slow on very large pages:
<script async
src="https://sharedlayers.com/comments.umd.js"
data-key="sl_embed_…"
data-snapshots="off">
</script>
With snapshots off, nothing visual leaves the page. Comments still carry the element's selector and a short text label; see What leaves the page.
data-project-id / projectId
Before embed keys existed the snippet carried a project id. Those snippets keep working and are not going away. Two things are different on this path: the script checks the licence against the project rather than the account, and Google sign-in is not offered, because the sign-in popup verifies the calling site against a key. If you have one of these snippets, swapping the attribute for a data-key from the dashboard is the upgrade. Existing comments stay where they are.