`<sciflow-reference-list>` web component¶

<sciflow-reference-list> renders a draggable, highlightable list of references. It is shipped by @sciflow/editor-start and registered when you import the bundle. No Lit knowledge is required — treat it like any other custom element: set properties, listen to events if needed.

Each reference must include id and rawReference. rawReference is the bibliography string — the full reference-list entry (not the short in-text citation). It can be any formatted bibliography string (including a handwritten entry) and may contain lightweight HTML such as <i> for italics. Set mimeType for non-CSL payloads; defaults to application/vnd.citationstyles.csl+json. Use application/vnd.openalex+json for OpenAlex or your own type if your integration understands it.

Naming in external systems

Some systems use a different field name for the bibliography string. OJS, for example, stores it as rawCitation — which in SciFlow terminology would be a raw citation (an in-text label like "(Author, 2024)"), not a reference-list entry. Map rawCitation → rawReference on import. See the OJS Integration Guide.

Usage¶

<sciflow-reference-list id="references"></sciflow-reference-list>

const referenceList = document.getElementById('references');
referenceList.references = latestReferences; // array of CSL-like objects
referenceList.highlight(['ref-1', 'ref-2']); // optional highlighted ids

Properties¶

references: Array — list of references to render; supports rawReference, author, title, issued, and so on (id and rawReference are required; set mimeType for anything besides CSL JSON.)
highlightedIds: string[] — IDs to highlight; can also be set via highlight(ids).
cursorActive: boolean — when true, enables the Cite button on each row. Set this to true once the editor has an active cursor (for example, on editor-selection-change), and reset it to false when a new document loads. See Cite button wiring.
empty-text attribute — message when no references exist.

Drag payloads¶

Each item sets: - application/json: { type: 'reference', id, text, reference } - application/x-sciflow-reference: 'sidebar' - text/plain: "[id]" or the display text

Drop behavior in the editor¶

When you drag a reference into the editor, citation insertion supports two modes:

Insert at caret/space: dropping into an empty insertion point creates a citation with default visible text (for example [reference-id]).
Convert existing text: dropping onto existing text can convert that text into a citation while preserving what the reader sees.

For text conversion, the editor resolves the drop target as follows:

If dropped inside (...), the full parenthesized expression is converted.
If dropped inside [...], the full bracketed expression is converted.
If dropped on plain prose (for example Muller in as seen in Muller 2022), only the word under the drop point is converted.

In all conversion cases:

The dropped reference id is written to citation source metadata.
The converted text remains the citation's visible content.
Dropping another reference onto that citation appends metadata without rewriting the existing visible citation text.

Connecting to the editor¶

Listen to editor events and push data into the list:

const editor = document.querySelector('sciflow-editor');
const refList = document.querySelector('sciflow-reference-list');

editor.addEventListener('editor-change', (event) => {
  const { doc, references } = event.detail;
  refList.references = Array.isArray(references) ? references : collectReferencesFromDoc(doc);
});

editor.addEventListener('editor-selection-change', (event) => {
  const ids = extractCitationIds(event.detail); // derive citation ids from selection
  refList.highlight(ids);
});

This mirrors the demo wiring: editor-change updates the list contents, and editor-selection-change drives highlights.

Events¶

Event	When fired	`detail`
`sciflow-insert-citation`	User clicks the Cite button on a row	`{ reference }` — the full reference object

The event bubbles and is composed, so it crosses shadow DOM boundaries and can be caught on the host document.

Cite button wiring¶

Each reference row shows a Cite button that is enabled only when cursorActive is true. This prevents insertion into an unknown position.

The recommended wiring pattern using editor-selection-change and editor-ready:

const editor = document.querySelector('sciflow-editor');
const refList = document.querySelector('sciflow-reference-list');

// Enable the Cite button as soon as the editor has a cursor
editor.addEventListener('editor-selection-change', () => {
  refList.cursorActive = true;
});

// Reset when a new document loads (cursor position is no longer valid)
editor.addEventListener('editor-ready', () => {
  refList.cursorActive = false;
});

// Handle the button click
refList.addEventListener('sciflow-insert-citation', (event) => {
  const { reference } = event.detail;
  editor.commands?.commands?.insertCitation?.({
    items: [{ id: reference.id }],
    text: reference.rawReference,
  });
});

Ghost cursor

Because clicking a sidebar button would normally blur the editor (losing the cursor position), the Cite button calls event.preventDefault() on mousedown to keep editor focus alive. Pair this with ghostCursorFeature (exported from @sciflow/editor-start) so the user can always see where the citation will be inserted — even after they interact with the sidebar. See Reference Integration for setup details.

Styling¶

<sciflow-reference-list> renders in shadow DOM, so ordinary page CSS can't reach its internals, and its default type sizes are set in rem/em — rem always resolves against the document root (not the host), so setting font-size on the host element alone won't resize the item text. Retheme via CSS custom properties on the host instead, the same way you'd override --sciflow-editor-* chrome vars (see Web Component API):

const refList = document.querySelector('sciflow-reference-list');
refList.setAttribute('style', `
  --sciflow-reference-item-size: 0.875rem;
  --sciflow-reference-meta-size: 0.75rem;
`);

Or inject them into the shadow root directly — a plain inline style attribute or a global stylesheet rule targeting the element both work, since custom properties inherit through the shadow boundary from the host.

Property	Applies to	Default (unset)
`--sciflow-reference-item-size`	Reference list item text (the formatted citation)	`0.8rem`
`--sciflow-reference-meta-size`	Reference row metadata — the ID chip, Cite button, and drag handle	`0.8em` (ID chip) / `0.7em` (Cite button, drag handle)

Metadata stays em-relative by default

--sciflow-reference-meta-size's fallback is 0.8em/0.7em, not a fixed length — the metadata row has no font-size of its own today, so it cascades from whatever context the element is rendered in. Leaving the property unset preserves that exact cascading behavior (zero visual change for existing integrations); setting it replaces the cascade with your fixed value across the ID chip, Cite button, and drag handle at once.

For the equivalent properties on <sciflow-outline>, see its Styling section.

<sciflow-reference-list> web component¶