Pinned Blocks

Keep selected child blocks pinned to the top of their current parent, even as blocks move and siblings are reorganized.

Features

• Pin selected references in the linked reference section to the top of the results.

• Pin, unpin, or toggle the focused block from the command palette.

• Pin or unpin any block from the block context menu.

• Keep multiple pinned siblings at the top in their current pinned-group order.

• Drag pinned blocks to reorder them within the pinned group.

• Move pinned blocks to another parent and keep them pinned in the new pinned group.

• Reorder the real Roam outline with Roam's native block reorder API; no duplicate shelf or hidden source blocks.

• Watch pinned parents so regular blocks inserted above or between pinned blocks are moved below the pinned group.

• Mark pinned blocks with a small pin indicator and stable CSS hooks for custom styling.

• Share pin state between collaborators through graph-backed records on roam/js/pinned-blocks.

Linked reference pins

Hover over a linked reference or focus it with the keyboard to reveal its pin button. Active pins stay visible. Use the pin button beside a linked reference to keep it at the top of that page's linked reference results. Click the active pin button to unpin it. Pinned results initially appear expanded at the top, without a section heading or count. Use the caret beside a pinned block’s source-page title to collapse or expand that reference. Collapsing keeps the title visible and the block pinned; the collapsed state lasts while the pinned result remains on screen.

Pinned results show a clickable source page title (Shift-click opens the sidebar) and retain Roam's native block controls. References within page titles can also be pinned using the pin beside their source heading. A pinned title stays separate from pins on individual blocks from that page. Pinned results follow the order in which their pins are saved. The pin button shows a loading state while saving.

Daily note pages and the Daily Notes view are supported, including collapsed reference groups. Use the Up and Down arrow keys on a pin button to move between the pin controls in their displayed order. Tab visits the pinned section first, then the remaining native reference controls.

Reference pins are saved separately for each target page or block under roam/js/pinned-blocks and shared with collaborators running the extension. They change the displayed reference order without changing source block order. Saved reference pins render immediately at the top, including references Roam has not lazy-loaded yet. Once the pinned copy has rendered successfully, the extension hides its original row when Roam loads it. While rendering is pending or has failed, the original row remains available. A failed pinned copy offers a Retry button. Unpinning removes the top copy and restores the original row. Roam's include/remove filters still apply to pinned copies. Deleted blocks and blocks that no longer reference the target are not shown.

Pin controls near bullets

Enable Show pin controls near bullets in the Pinned Blocks settings to pin or unpin outline blocks using buttons beside their bullets. In this mode, linked-reference buttons also appear on the left, near their bullets (or beside the heading for page-title references). Unpinned controls appear on hover or keyboard focus; active pins stay visible.

Linked-reference pins share the outline pin column. The controls sit outside the reference content without shifting source headings, bullets, or text, and align with the first line when a block wraps.

Unpinned icons are light gray; pinned icons are dark gray. Hovering over or focusing a pin adds a subtle background. Controls stay visible as you move from a block to its pin. At narrow pane edges, the buttons become slightly narrower and move inward to stay clear of the sidebar and collapse carets.

The setting is off by default. Turning it off restores outline pin indicators and linked-reference buttons on the right. Outline pins still reorder siblings under their parent; linked-reference pins still affect only the target's reference results.

Multiplayer graphs

Collaborators running Pinned Blocks in the same graph share the same pin records and pinned order. Pin membership is stored under roam/js/pinned-blocks, while order follows the real Roam outline.

Pinned Blocks changes real sibling order with Roam's native reorder API, so its changes are also visible to collaborators who do not run the extension. Those collaborators will not see pin indicators and may not understand why a block moves back into the pinned group.

Storage

Pinned Blocks creates roam/js/pinned-blocks with a notice explaining that the page is extension-managed. Each pin is stored as a separate child record using the roamjs-pinned-blocks block-props namespace. The page and notice remain when there are no pins; pin-data children are removed.

Pinned Blocks does not use browser local storage.

Commands

• Pinned Blocks: Toggle Pin Focused Block
• Pinned Blocks: Pin Focused Block
• Pinned Blocks: Unpin Focused Block

Styling

Pinned Blocks adds these classes to the rendered outline:

• .roamjs-pinned-blocks-block
• .roamjs-pinned-blocks-block-pinned

The default indicator is rendered on .roamjs-pinned-blocks-block-pinned::before and can be adjusted with CSS variables:

• --roamjs-pinned-blocks-indicator-color
• --roamjs-pinned-blocks-indicator-size
• --roamjs-pinned-blocks-indicator-left
• --roamjs-pinned-blocks-sidebar-indicator-left
• --roamjs-pinned-blocks-indicator-top
• --roamjs-pinned-blocks-indicator-opacity
• --roamjs-pinned-blocks-indicator-z-index