sref
- Attribute
sref- Type
string- Default
""
The Sefaria reference to load when data isn't set.
Created/edited by GitHub Copilot; pending human review.
Components reference
This page lists the attributes, properties, data, empty states, events, and style settings of the toolkit's five elements. The generator builds it from the package's custom-elements.json.
The elements are registered when you load the script tag or when you import the package root with import "@sefaria/web-components";. The element subpaths, such as @sefaria/web-components/source-card, don't register their element. They export types and a few helpers.
Which release this describes
This page documents the code on the main branch. The source stamp is not an npm release or a development snapshot. This copy was built from commit 6fde603.
Install an exact npm version or use a version-pinned npm CDN module. The npm alpha tag moves between reviewed prereleases. It is not a main-build snapshot. Older pinned releases keep their own behavior and can lack APIs added since. Install and status lists package commands and jsDelivr/UNPKG files.
Elements
- Text Segment:
<sefaria-text-segment> - Bilingual Segment:
<sefaria-bilingual-segment> - Source Card:
<sefaria-source-card> - Connections Panel:
<sefaria-connections-panel> - Reader:
<sefaria-reader>
Text Segment
<sefaria-text-segment>. Shows the text of one passage in one selected edition. How to use it.
Attributes and properties
Set an attribute in HTML or a property in JavaScript. If a property has no attribute, set it in JavaScript.
data
- Attribute
- None. Set it in JavaScript.
- Type
unknown | undefined- Default
undefined
Sefaria API response data to render. When it's set, the element doesn't fetch anything.
source
- Attribute
- None. Set it in JavaScript.
- Type
SefariaDataSource | undefined- Default
undefined
Where this element gets its data, instead of the shared data source.
versionLanguage
- Attribute
version-language- Type
string | undefined- Default
undefined
Language of the edition to show, instead of the primary edition.
versionTitle
- Attribute
version-title- Type
string | undefined- Default
undefined
version-title alone chooses another edition in the original language. To choose a translation by title, also set translation-language.
translationLanguage
- Attribute
translation-language- Type
string | undefined- Default
undefined
Preferred translation language. Can't be combined with versionLanguage.
translationFallback
- Attribute
translation-fallback- Type
"default" | "none"- Default
"none"
What happens when the preferred translation language is missing: default loads Sefaria's default translation, none shows a status such as "No french text.".
vocalizationMode
- Attribute
vocalization-mode- Type
VocalizationMode- Default
"taamim_and_nikkud"
How much Hebrew vowel and cantillation marking to keep. none removes both.
selectedVersion
- Attribute
- None. Set it in JavaScript.
- Type
TextSegmentSelectedVersionInfo | undefined- Default
- —
- Access
- Read-only
Details of the edition currently shown.
status
- Attribute
- None. Set it in JavaScript.
- Type
SefariaElementStatus- Default
- —
- Access
- Read-only
Loading state: "empty", "loading", "ready" or "error".
Data
data takes the body of a successful GET /api/v3/texts/{tref} response, typed CoreV3TextsResponse from @sefaria/api-client. It also accepts a TextSegmentSelectedData object with kind: "selected". When data is defined, the element uses it instead of loading sref, even when it is invalid. It treats the value as a status 200 response.
Empty state
The element shows its empty state when the chosen edition has no text. The message depends on how the edition was chosen. If the default primary edition is missing, you see No primary text is available. If an edition you selected has no text, you can see a message that names that edition. On some paths, the element shows the response's warning instead.
Events
sefaria-text-segment-error
- Detail
- error is the original failure. sref is the reference that was loading.
- Cancelable
- No
Reports a failure while loading or validating data from sref.
CSS parts
CSS parts: none.
Bilingual Segment
<sefaria-bilingual-segment>. Shows one passage in its primary edition, together with a translation. The primary edition is the one marked isPrimary. How to use it.
Attributes and properties
Set an attribute in HTML or a property in JavaScript. If a property has no attribute, set it in JavaScript.
sref
- Attribute
sref- Type
string- Default
""
The Sefaria reference to load when data isn't set.
data
- Attribute
- None. Set it in JavaScript.
- Type
unknown | undefined- Default
undefined
Sefaria API response data to render. When it's set, the element doesn't fetch anything.
source
- Attribute
- None. Set it in JavaScript.
- Type
SefariaDataSource | undefined- Default
undefined
Where this element gets its data, instead of the shared data source.
primaryVersionTitle
- Attribute
primary-version-title- Type
string | undefined- Default
undefined
Exact title of the edition to show as the primary text.
translationVersionTitle
- Attribute
translation-version-title- Type
string | undefined- Default
undefined
Exact title of the edition to show as the translation.
translationLanguage
- Attribute
translation-language- Type
string | undefined- Default
undefined
Preferred translation language. translationFallback controls what happens when Sefaria has none.
translationFallback
- Attribute
translation-fallback- Type
"default" | "none"- Default
"none"
What happens when the preferred translation language is missing: default loads Sefaria's default translation, none shows a status such as "No french text.".
contentLanguage
- Attribute
content-language- Type
BilingualSegmentContentLanguage- Default
"both"
Which text to show: primary, translation or both.
layout
- Attribute
layout- Type
BilingualSegmentLayout- Default
"auto"
How the two texts are arranged: auto, stacked or side-by-side.
sideOrder
- Attribute
side-order- Type
BilingualSegmentSideOrder- Default
"primary-first"
Which text comes first side by side: primary-first or translation-first.
vocalizationMode
- Attribute
vocalization-mode- Type
VocalizationMode- Default
"taamim_and_nikkud"
How much Hebrew vowel and cantillation marking to keep. none removes both.
status
- Attribute
- None. Set it in JavaScript.
- Type
SefariaElementStatus- Default
- —
- Access
- Read-only
Loading state: "empty", "loading", "ready" or "error".
Data
data takes the body of a successful GET /api/v3/texts/{tref} response, typed CoreV3TextsResponse from @sefaria/api-client. When data is defined, the element uses it instead of loading sref, even when it is invalid. It treats the value as a status 200 response.
Empty state
The element shows its empty state when neither side has text. Each missing side has its own message, such as No primary text is available. or No translation text is available. The element can show the response's warning for that side instead. When only one side is missing, you see the other side's text and the missing side's message. contentLanguage filters which sides are shown.
Events
sefaria-bilingual-segment-error
- Detail
- error is the original failure. sref is the reference that was loading.
- Cancelable
- No
Reports a failure while loading or validating data from sref.
CSS parts
CSS parts: none.
Source Card
<sefaria-source-card>. Shows a passage as a card. The card has a heading, the text in the primary edition, a translation, and the title of each edition shown. When an edition's source is a valid http(s) address, the title links to it. Any other source appears as plain text. How to use it.
Attributes and properties
Set an attribute in HTML or a property in JavaScript. If a property has no attribute, set it in JavaScript.
sref
- Attribute
sref- Type
string- Default
""
The Sefaria reference to load when data isn't set.
data
- Attribute
- None. Set it in JavaScript.
- Type
unknown | undefined- Default
undefined
Sefaria API response data to render. When it's set, the element doesn't fetch anything.
source
- Attribute
- None. Set it in JavaScript.
- Type
SefariaDataSource | undefined- Default
undefined
Where this element gets its data, instead of the shared data source.
primaryVersionTitle
- Attribute
primary-version-title- Type
string | undefined- Default
undefined
Exact title of the edition to show as the primary text.
translationVersionTitle
- Attribute
translation-version-title- Type
string | undefined- Default
undefined
Exact title of the edition to show as the translation.
translationLanguage
- Attribute
translation-language- Type
string | undefined- Default
undefined
Preferred translation language. translationFallback controls what happens when Sefaria has none.
translationFallback
- Attribute
translation-fallback- Type
"default" | "none"- Default
"default"
What happens when the preferred translation language is missing: default loads Sefaria's default translation, none shows a status such as "No french text.".
contentLanguage
- Attribute
content-language- Type
BilingualPairContentLanguage- Default
"both"
Which text to show: primary, translation or both.
layout
- Attribute
layout- Type
BilingualPairLayout- Default
"auto"
How each pair of texts is arranged: auto, stacked or side-by-side.
sideOrder
- Attribute
side-order- Type
BilingualPairSideOrder- Default
"primary-first"
Which text comes first side by side: primary-first or translation-first.
vocalizationMode
- Attribute
vocalization-mode- Type
VocalizationMode- Default
"taamim_and_nikkud"
How much Hebrew vowel and cantillation marking to keep. none removes both.
showAddressLabels
- Attribute
- None. Set it in JavaScript.
- Type
boolean- Default
true
Whether small reference labels are shown beside the texts.
selectable
- Attribute
selectable- Type
boolean- Default
false
Lets readers select the verses that have their own reference.
selectedPosition
- Attribute
- None. Set it in JavaScript.
- Type
readonly number[] | undefined- Default
undefined
Position of the selected verse, as an array of numbers rather than a reference.
hideAttributions
- Attribute
hide-attributions- Type
boolean- Default
false
Hides the edition attribution.
status
- Attribute
- None. Set it in JavaScript.
- Type
SefariaElementStatus- Default
- —
- Access
- Read-only
Loading state: "empty", "loading", "ready" or "error".
Data
data takes the body of a successful GET /api/v3/texts/{tref} response, typed CoreV3TextsResponse from @sefaria/api-client. When data is defined, the element uses it instead of loading sref, even when it is invalid. It treats the value as a status 200 response.
Empty state
The element shows its empty state when the response has no text for either side. The card keeps its heading and edition details. It shows why each side is missing, such as No primary text is available.
Events
sefaria-source-select
- Detail
- position is the selected segment's position as an array of numbers. ref is its reference.
- Cancelable
- No
Reports that a reader selected one item in the source card.
sefaria-source-card-error
- Detail
- error is the original failure. sref is the reference that was loading.
- Cancelable
- No
Reports a failure while loading or validating data from sref.
CSS parts
CSS parts: none.
Connections Panel
<sefaria-connections-panel>. Lists the commentaries and other texts that Sefaria connects to a reference. It groups them by category. How to use it.
Attributes and properties
Set an attribute in HTML or a property in JavaScript. If a property has no attribute, set it in JavaScript.
sref
- Attribute
sref- Type
string- Default
""
The Sefaria reference whose connections to load.
source
- Attribute
- None. Set it in JavaScript.
- Type
SefariaDataSource | undefined- Default
undefined
Where this element gets its data, instead of the shared data source.
withText
- Attribute
with-text- Type
boolean- Default
true
Whether the links include the connected texts.
category
- Attribute
category- Type
string | undefined- Default
undefined
Category of the loaded links to show.
page
- Attribute
page- Type
number- Default
0
Zero-based page of the loaded links to show.
showPreviews
- Attribute
show-previews- Type
boolean- Default
true
Shows or hides the text previews already loaded, without fetching more.
vocalizationMode
- Attribute
vocalization-mode- Type
VocalizationMode- Default
"taamim_and_nikkud"
How much Hebrew vowel and cantillation marking to keep in previews. none removes both.
status
- Attribute
- None. Set it in JavaScript.
- Type
SefariaElementStatus- Default
- —
- Access
- Read-only
Loading state: "empty", "loading", "ready" or "error".
Data
It has no data property. To give it local data, set source to { kind: "custom", loader }, where the custom loader's getText and getLinks functions answer from your data. See Give components your own data.
Empty state
The element shows its empty state when no text connections remain after the element leaves out sheet links. A response with only sheets is empty too. The message is No text connections were returned.
Events
sefaria-connections-category-change
- Detail
- category is the chosen category's ID, or null for all categories.
- Cancelable
- Yes
Asks to show a different connection category. Call preventDefault() to stop the panel from switching to that category and returning to the first page.
sefaria-connections-preview-request
- Detail
- No fields.
- Cancelable
- Yes
Requests connection previews. The element loads them unless a listener cancels the event. Call preventDefault() to stop the panel from loading previews itself. If you don't call it, a panel that loads from sref requests the connections again with their text.
sefaria-connections-page-change
- Detail
- page is the zero-based page number.
- Cancelable
- Yes
Asks to show a different page of connections. Call preventDefault() to stop the panel from changing page.
sefaria-connection-select
- Detail
- id is the connection's ID. targetRef is the connected text's reference.
- Cancelable
- Yes
Reports that a reader selected one connected reference. Call preventDefault() to do nothing. The panel has no default action for this event.
sefaria-connections-panel-error
- Detail
- error is the original failure. sref is the reference that was loading.
- Cancelable
- No
Reports a failure while loading or validating data from sref.
CSS parts
CSS parts: none.
Reader
<sefaria-reader>. Shows a passage with its connected texts. Readers can move between them. How to use it.
Attributes and properties
Set an attribute in HTML or a property in JavaScript. If a property has no attribute, set it in JavaScript.
sref
- Attribute
sref- Type
string- Default
""
The reference the Reader starts from. Navigating inside the Reader doesn't change it.
source
- Attribute
- None. Set it in JavaScript.
- Type
SefariaDataSource | undefined- Default
undefined
Where this element gets its data, instead of the shared data source.
translationLanguage
- Attribute
translation-language- Type
string | undefined- Default
undefined
Preferred translation language, for the starting text and texts you navigate to.
translationFallback
- Attribute
translation-fallback- Type
"default" | "none"- Default
"default"
What happens when the preferred translation language is missing: default loads Sefaria's default translation, none shows a status such as "No french text.".
primaryVersionTitle
- Attribute
primary-version-title- Type
string | undefined- Default
undefined
Exact title of the primary edition for the starting reference.
translationVersionTitle
- Attribute
translation-version-title- Type
string | undefined- Default
undefined
Exact title of the translation edition for the starting reference.
hideAttributions
- Attribute
hide-attributions- Type
boolean- Default
false
Hides the edition attribution on the source card.
activePane
- Attribute
active-pane- Type
ReaderPane- Default
"source"
Which pane the compact layout shows: source or connections.
chatExport
- Attribute
chat-export- Type
boolean- Default
false
Shows a button that sends the selected reference to your page's chat, when one is selected.
contentLanguage
- Attribute
content-language- Type
BilingualPairContentLanguage- Default
"both"
Which text the source card shows: primary, translation or both.
layout
- Attribute
layout- Type
BilingualPairLayout- Default
"auto"
How the source card arranges its two texts: auto, stacked or side-by-side.
sideOrder
- Attribute
side-order- Type
BilingualPairSideOrder- Default
"primary-first"
Which text comes first side by side: primary-first or translation-first.
showConnectionPreviews
- Attribute
show-connection-previews- Type
boolean- Default
true
Whether connection previews are shown.
vocalizationMode
- Attribute
vocalization-mode- Type
VocalizationMode- Default
"taamim_and_nikkud"
How much Hebrew vowel and cantillation marking to keep. none removes both.
status
- Attribute
- None. Set it in JavaScript.
- Type
SefariaElementStatus- Default
- —
- Access
- Read-only
Loading state: "empty", "loading", "ready" or "error".
currentEntryId
- Attribute
- None. Set it in JavaScript.
- Type
string | undefined- Default
- —
- Access
- Read-only
The ID of the current history entry.
selectedRef
- Attribute
- None. Set it in JavaScript.
- Type
string | undefined- Default
- —
- Access
- Read-only
The selected reference, when there is one.
rootLoading
- Attribute
- None. Set it in JavaScript.
- Type
boolean- Default
- —
- Access
- Read-only
Whether the starting text is still loading.
readerError
- Attribute
- None. Set it in JavaScript.
- Type
string | undefined- Default
- —
- Access
- Read-only
The error message, when the latest action failed.
canGoBack
- Attribute
- None. Set it in JavaScript.
- Type
boolean- Default
- —
- Access
- Read-only
Whether Back can return to an earlier entry.
historyTruncated
- Attribute
- None. Set it in JavaScript.
- Type
boolean- Default
- —
- Access
- Read-only
Whether older history entries were dropped to stay within the history limit.
Data
It has no data property. To give it local data, set source to { kind: "custom", loader }, where the custom loader's getText and getLinks functions answer from your data. See Give components your own data.
Empty state
A Reader that has never had sref is blank. Its status is empty. A missing pane shows Source text is not available for this entry. or Connections are not available for this entry. The Reader reports a passage with no text as a source failure, not as an empty Source Card. A valid links response with no text connections shows the Connections Panel's empty message.
Events
sefaria-reader-back
- Detail
- originEntryId, the entry the Reader was showing
- Cancelable
- Yes
Requests navigation to the previous entry. Call preventDefault() to stop the Reader from going back.
sefaria-reader-history-activate
- Detail
- originEntryId is the entry the Reader was showing. entryId is the history entry chosen. label is its label.
- Cancelable
- Yes
Asks to return to one saved history entry. Call preventDefault() to stop the Reader from returning to that entry.
sefaria-reader-pane-change
- Detail
- originEntryId is the entry the Reader was showing. pane is "source" or "connections".
- Cancelable
- Yes
Asks to show a different pane in the compact layout. Call preventDefault() to stop the Reader from switching pane.
sefaria-reader-chat-export
- Detail
- originEntryId is the entry the Reader was showing. targetRef is the reference to send.
- Cancelable
- Yes
Asks your page to send a reference to chat. Call preventDefault() to do nothing. The Reader has no default action. Your page handles the export.
sefaria-reader-source-select
- Detail
- originEntryId is the entry the Reader was showing. position and ref are the same as in sefaria-source-select.
- Cancelable
- Yes
Reports that a reader selected one item in the source card. Call preventDefault() to stop the Reader from selecting that segment.
sefaria-reader-connections-category-change
- Detail
- originEntryId is the entry the Reader was showing. category is the same as in sefaria-connections-category-change.
- Cancelable
- Yes
Asks to show a different connection category. Call preventDefault() to stop the Reader from switching category.
sefaria-reader-connections-page-change
- Detail
- originEntryId is the entry the Reader was showing. page is the same as in sefaria-connections-page-change.
- Cancelable
- Yes
Asks to show a different connection page. Call preventDefault() to stop the Reader from changing page.
sefaria-reader-connection-select
- Detail
- originEntryId is the entry the Reader was showing. id and targetRef are the same as in sefaria-connection-select.
- Cancelable
- Yes
Reports that a reader selected one connected reference. Call preventDefault() to stop the Reader from opening the connected text.
sefaria-reader-connections-preview-request
- Detail
- originEntryId
- Cancelable
- Yes
Requests connection previews. The element loads them unless a listener cancels the event. Call preventDefault() to stop the Reader from loading previews.
sefaria-reader-error
- Detail
- error is the original failure. sref is the reference the Reader was loading when the failure happened.
- Cancelable
- No
Reports a failure while loading the starting text or a text you navigate to, or when loading is disabled.
Slots
| Slot | Description |
|---|---|
toolbar-actions | Host-owned actions placed after the Reader's built-in toolbar controls. |
CSS parts
Style these from your page with ::part(name).
| Part | Description |
|---|---|
toolbar | Container for compact pane and host action controls. |
history | Back and retained-history controls. |
source-pane | Scrollable source-text pane. |
connections-pane | Scrollable connections pane. |
Events
Each element dispatches CustomEvents that bubble and cross shadow roots. Listen for them with addEventListener on the element or an ancestor. For a cancelable event, call preventDefault() in your listener to stop the element's own action. The element acts after your listener returns.
Invalid supplied data puts Text Segment, Bilingual Segment and Source Card into their error state. They dispatch no error event for it. Their error events report only failures while loading sref. The Reader has no data property. It dispatches sefaria-reader-error when loading fails or loading is disabled.
Make components respond to each other shows how to use them.
Style settings
The elements share these CSS custom properties. Not every element uses every one. Set them on the element or on any ancestor. Match your site's look shows how.
--sefaria-surface
- Default
transparent- Used by
sefaria-bilingual-segment, sefaria-connections-panel, sefaria-reader, sefaria-source-card, sefaria-text-segment
Primary surface color. Text Segment is transparent unless this is set.
--sefaria-surface-muted
- Default
light-dark(#f5f1e8, #222521)- Used by
sefaria-reader, sefaria-source-card
Muted surface color.
--sefaria-fg
- Default
light-dark(#25231f, #f1eee7)- Used by
sefaria-bilingual-segment, sefaria-connections-panel, sefaria-reader, sefaria-source-card, sefaria-text-segment
Primary foreground color.
--sefaria-fg-muted
- Default
light-dark(#6d675d, #bdb7ac)- Used by
sefaria-bilingual-segment, sefaria-connections-panel, sefaria-reader, sefaria-source-card, sefaria-text-segment
Muted foreground color.
--sefaria-border
- Default
light-dark(#d7cfc1, #555b53)- Used by
sefaria-connections-panel, sefaria-reader, sefaria-source-card
Standard border color.
--sefaria-border-strong
- Default
light-dark(#aaa094, #73796f)- Used by
- —
Reserved. No component uses it yet. Strong border color.
--sefaria-accent
- Default
light-dark(#8e2449, #ff93b4)- Used by
sefaria-reader, sefaria-source-card
Accent and focus color.
--sefaria-accent-soft
- Default
light-dark(rgb(142 36 73 / 10%), rgb(255 147 180 / 14%))- Used by
- —
Reserved. No component uses it yet. Translucent accent surface.
--sefaria-danger
- Default
light-dark(#9c1c1c, #ffaaa4)- Used by
- —
Reserved. No component uses it yet. Error foreground color.
--sefaria-link
- Default
light-dark(#8e2449, #ff93b4)- Used by
sefaria-reader, sefaria-source-card
Link foreground color.
--sefaria-shadow
- Default
0 1rem 3rem rgb(0 0 0 / 28%)- Used by
- —
Reserved. No component uses it yet. Elevated-surface shadow.
--sefaria-panel-radius
- Default
0.75rem- Used by
sefaria-connections-panel, sefaria-reader, sefaria-source-card
Panel corner radius.
--sefaria-control-radius
- Default
0.3rem- Used by
sefaria-connections-panel, sefaria-source-card
Control corner radius.
--sefaria-font-scale
- Default
1- Used by
sefaria-bilingual-segment, sefaria-connections-panel, sefaria-reader, sefaria-source-card, sefaria-text-segment
Component font-size multiplier.
--sefaria-font-hebrew
- Default
"Noto Serif Hebrew", "SBL Hebrew", "Times New Roman", serif- Used by
sefaria-connections-panel, sefaria-source-card, sefaria-text-segment
Hebrew body font stack.
--sefaria-font-english
- Default
Georgia, "Times New Roman", serif- Used by
sefaria-bilingual-segment, sefaria-connections-panel, sefaria-reader, sefaria-source-card, sefaria-text-segment
English body font stack.
--sefaria-font-label-hebrew
- Default
"Noto Sans Hebrew", system-ui, sans-serif- Used by
- —
Reserved. No component uses it yet. Hebrew label font stack.
--sefaria-font-label-english
- Default
system-ui, sans-serif- Used by
sefaria-reader
English label font stack.