Show one passage

The Text Segment, <sefaria-text-segment>, shows the text of one passage, such as Micah 6:8, in one edition. It shows only the text. To credit the edition, see Show an attributed passage. For a passage in Hebrew and a translation side by side, see Show Hebrew and translation together.

Show the default text

Set sref to the reference. By default, the segment shows the edition Sefaria marks as primary (isPrimary). That is usually, but not always, the Hebrew or original text. To choose another edition, see Choose which text to show.

The default text

For Micah 6:8, the primary edition is the Hebrew Miqra according to the Masorah.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<sefaria-text-segment sref="Micah 6:8"></sefaria-text-segment>

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

Match your site's colors and fonts

Set --sefaria-* CSS custom properties, such as --sefaria-fg for text color and --sefaria-font-scale for size, on an element that contains the segment. Style the segment's own box, such as its padding and border, as you would any element.

Style a passage

A containing div sets a warm background, brown text, serif fonts, and a larger font scale. The element's own box gets padding, a rounded corner, an accent border, and italic text.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<style>
  :root {
    color-scheme: light dark;
  }

  .styled-passage {
    --sefaria-surface: light-dark(#fdf3dc, #3a2f1c);
    --sefaria-fg: light-dark(#5a2d0c, #f6d9a8);
    --sefaria-font-hebrew: "Frank Ruehl CLM", "David", "Times New Roman", serif;
    --sefaria-font-english: Georgia, "Times New Roman", serif;
    --sefaria-font-scale: 1.35;
  }

  .styled-passage sefaria-text-segment {
    display: block;
    padding: 1rem 1.25rem;
    border-inline-start: 6px solid light-dark(#b5651d, #e0a458);
    border-radius: 12px;
    font-style: italic;
  }
</style>
<div class="styled-passage">
  <sefaria-text-segment sref="Micah 6:8"></sefaria-text-segment>
</div>

These styling rules apply to every toolkit component:

• The same --sefaria-* properties style every component. Set them once on :root to style the whole page.
• Your page's CSS selectors can't reach inside a component.
• Changing styles doesn't load the text again.

Learn more: Match your site's look for every property, dark mode, and why selectors can't reach inside.

Choose which text to show

To get	Set	What happens
The default edition	Nothing	Sefaria's primary edition.
A translation in a language	translation-language	A translation in that language. If Sefaria has none, the segment shows a short notice (see When the language isn't available).
A language family, strictly	version-language	Text in that language family only. There is no fallback, and it doesn't pin one edition.
One exact edition	version-title	Alone, that title among the primary editions. With version-language, that title in that language. With translation-language, that title in your preferred translation language.

Rules for these attributes

• Write languages as full lowercase names, such as french or english. Codes such as fr don't work.
• An exact title never falls back.
• You can't combine translation-language and version-language. If you do, the element shows the error translation-language and version-language cannot be combined.

For every attribute, see Reference › Components.

A language, then an exact edition

The first segment asks for French by translation-language. The second asks for an exact English edition by version-language and version-title.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<sefaria-text-segment
  sref="Micah 6:8"
  translation-language="french"
></sefaria-text-segment>
<sefaria-text-segment
  sref="Micah 6:8"
  version-language="english"
  version-title="The Holy Scriptures: A New Translation (JPS 1917)"
></sefaria-text-segment>

When the language isn't available

If Sefaria reports that it has no text in your translation-language, the segment shows a short status message, such as No french text.. Screen readers announce it. By default (translation-fallback="none"), the segment makes one request. Its status is empty, and there is no error or error event.

To show Sefaria's default translation instead, set translation-fallback="default". The segment makes one more request and shows that translation with no notice. That translation isn't always English.

No fallback, then the default translation

Both ask for French on Berakhot 2a:1. The first uses the default none and shows the notice. The second sets translation-fallback="default" and shows Sefaria's default translation.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<sefaria-text-segment
  sref="Berakhot 2a:1"
  translation-language="french"
></sefaria-text-segment>
<sefaria-text-segment
  sref="Berakhot 2a:1"
  translation-language="french"
  translation-fallback="default"
></sefaria-text-segment>

With translation-fallback="default" and a missing language, the segment makes two requests. An exact edition, or a language that exists but has empty text, doesn't fall back.

Control vowel points and cantillation

vocalization-mode changes Hebrew text:

• taamim_and_nikkud (the default) keeps vowel points and cantillation.
• nikkud keeps most vowel points and removes cantillation.
• none removes vowel points and cantillation, along with a few other marks such as the sof pasuq (׃). For the exact list, see Change vowels and cantillation.

Nikkud, then none

The same Hebrew with vowel points and no cantillation (nikkud), then with neither (none).

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@sefaria/web-components@0.1.0-alpha.0/dist/browser/sefaria-elements.js"
></script>
<sefaria-text-segment
  sref="Micah 6:8"
  vocalization-mode="nikkud"
></sefaria-text-segment>
<sefaria-text-segment
  sref="Micah 6:8"
  vocalization-mode="none"
></sefaria-text-segment>

Learn more: Clean up stored Sefaria text · Clean text and safety

When there's nothing to show

Situation	What readers see	status	Error event
Waiting for Sefaria	A loading message	loading	No
Sefaria can't be reached	On a first load, the error message as an alert. A failed load keeps the text already showing.	error	sefaria-text-segment-error
Sefaria says the text isn't a reference, or the supplied data is invalid	An error message	error	No
No text in your translation-language, or no sref and no data	A status message, or nothing	empty	No

Read status from the element in JavaScript. It is empty, loading, ready, or error. The error event fires only when Sefaria can't be reached. It bubbles and crosses the component boundary. Its event.detail holds { error, sref }. Invalid data doesn't fall back to sref.

For every empty state, see Reference › Components. For every event, see Reference › Components.

Read status and listen for errors

A good reference, a text that isn't a reference, and an empty element. 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-text-segment sref="Micah 6:8"></sefaria-text-segment>
<sefaria-text-segment sref="Not a book 3:4"></sefaria-text-segment>
<sefaria-text-segment></sefaria-text-segment>
<button type="button" id="check">Show each status</button>
<pre id="log"></pre>
<script type="module">
  const log = document.querySelector("#log");
  document.addEventListener("sefaria-text-segment-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-text-segment")) {
      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 data property to it. The segment then makes no requests. See Give components your own data.

Next steps

• Choose what text readers see to apply these choices across components.
• Reference › Components for every attribute.
• Text tools reference for the vocalization functions.