Show an attributed passage and let readers select it

This page has not been reviewed by a human.

The Source Card, <sefaria-source-card>, shows a whole passage in one block: a heading, the text of each verse, and where the text came from. It is also the first component here that tells your page what a reader did. It does this through the sefaria-source-select event.

What the card shows

Set sref to a reference such as Micah 6:6-8 or Micah 6:8. The card shows:

• A heading with the reference in English and Hebrew. The heading isn't a link.
• The passage's primary edition and a translation for each verse. A range such as Micah 6:6-8 shows each verse as its own item.
• Attribution for the editions shown.

The card takes the same text settings as Bilingual Segment, such as layout. See Show Hebrew and translation together. Three attributes matter most here:

• translation-language picks the translation language.
• translation-fallback is default or none. It is default on Source Card. The card then asks for Sefaria's default translation when yours is missing.
• hide-attributions hides the attribution and the fallback note.

For every attribute, see Reference › Components.

Read the attribution

Attribution appears once for the whole card, not once per verse. It has one line for each edition shown, labeled Primary text: or Translation:, followed by the edition's title and its language name. For example, Translation: THE JPS TANAKH: Gender-Sensitive Edition (english).

The card links the edition title to the edition's source only when Sefaria gives a valid http(s) address. The link opens in a new tab. Otherwise the title is plain text. The attribution doesn't show the license. For reuse rights, see Choose what text readers see.

By default, if Sefaria reports that your preferred translation language is missing, the card makes one more request. It asks for Sefaria's default translation, which isn't always English. The card adds a note naming the missing language and the one shown. An exact edition never falls back.

With translation-fallback="none", the card makes one request. The translation side says the language is missing. The primary side still shows. status is ready with no error.

hide-attributions hides the attribution lines and the fallback note.

Let readers select a verse

Add the selectable attribute. Each selectable verse gets a number button beside each text side that the card shows, normally Hebrew and English. A hidden or missing side has no button. Each button's accessible name is Select Micah 6:7, with the verse's own reference. Clicking the verse row works too. Keyboard users press Tab to reach the buttons, then Enter or Space. A selection fires sefaria-source-select. It bubbles and crosses the component boundary, so you can listen on the card or on a parent. The event also works with supplied data and makes no request. Its event.detail is { position, ref }, for example { position: [1], ref: "Micah 6:7" }. position is a list of numbers that locates the verse in the passage, counting from 0. For a range such as Micah 6:6-8 it is one number, so [1] is the second verse.

The card doesn't mark the choice itself. To show it, set selectedPosition to event.detail.position. The verse then appears selected, with an outline and aria-pressed. Setting it doesn't fire the event again.

The example shows a Cite button for the selected verse. Choose a verse, then choose the button to see its citation. The card adds selection buttons only when it can work out each verse's own reference. Some passages, such as ones that span chapters, still show but without selection buttons.

The example caps the card's height with max-height and overflow: auto, so a tall passage scrolls inside its box. Selection still works while you scroll.

To try changes, choose Edit, change the code, and choose Run.

Select a verse

Selecting a verse in Micah 6:6-8 shows it and offers a button to cite it.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<div style="max-height: 16rem; overflow: auto">
  <sefaria-source-card sref="Micah 6:6-8" selectable></sefaria-source-card>
</div>
<p id="selection">Select a verse number.</p>
<button id="cite" type="button" hidden></button>
<script type="module">
  const card = document.querySelector("sefaria-source-card");
  const output = document.querySelector("#selection");
  const cite = document.querySelector("#cite");
  card.addEventListener("sefaria-source-select", (event) => {
    const { position, ref } = event.detail;
    card.selectedPosition = position;
    output.textContent = `You selected ${ref} (position ${position.join(", ")}).`;
    cite.textContent = `Cite ${ref}`;
    cite.hidden = false;
  });
  cite.addEventListener("click", () => {
    output.textContent = `Cited: ${cite.textContent.slice(5)}.`;
  });
</script>

Learn more: Show commentary and connected texts · Make components respond to each other

How many requests it makes

A fresh load makes one request for the whole card. It makes two requests only when the translation fallback happens. With translation-fallback="none", it is always one request. The verses inside the card don't make their own requests, however many there are. With supplied data, the card makes none.

When there's nothing to show

The card's status property is empty, loading, ready, or error. Here is what each situation looks like:

Situation	What readers see	status	Error event
Waiting for Sefaria	A loading message	loading	No
Sefaria can't be reached	An error message	error	sefaria-source-card-error
Sefaria says the text isn't a reference	Sefaria's own message	error	No
The translation is missing and the fallback is off	The text, with a "no text" note on the translation side	ready	No
No sref and no data	Nothing	empty	No

Read status from the element in JavaScript.

To react to a failed load, listen for sefaria-source-card-error. Its event.detail holds { error, sref }. A failed load keeps the text already showing.

Invalid supplied data shows an error without falling back to sref. It doesn't send the event.

For every situation and event, see Reference › Components.

Read status and listen for errors

The example has a valid reference, a text that isn't a reference, and an empty card. Choose Show each status to log each one's status.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<sefaria-source-card sref="Micah 6:8"></sefaria-source-card>
<sefaria-source-card sref="Not a book 3:4"></sefaria-source-card>
<sefaria-source-card></sefaria-source-card>
<button type="button" id="check">Show each status</button>
<pre id="log"></pre>
<script type="module">
  const log = document.querySelector("#log");
  document.addEventListener("sefaria-source-card-error", (event) => {
    log.textContent += `Error for ${event.detail.sref}: ${event.detail.error.message}\n`;
  });
  document.querySelector("#check").addEventListener("click", () => {
    for (const element of document.querySelectorAll("sefaria-source-card")) {
      log.textContent += `"${element.sref}" is ${element.status}\n`;
    }
  });
</script>

Learn more: Troubleshoot a page

Use your own data

If you already have Sefaria's text response, set the card's data property to it. See Give components your own data.

Next steps

• Use with a framework to wire the card into your app.
• Show commentary and connected texts to show what a selected verse connects to.
• How the toolkit works and Sefaria's own texts and tools for background.
• Reference › Components for every attribute and event.