# Sefaria Frontend Toolkit

> Web components and TypeScript tools for showing texts from Sefaria's library on your own web pages. The components load and display sources by reference. The client fetches and checks Sefaria API responses, and the text tools make Sefaria's text HTML safe to display (`normalizeText`) and prepare it.

Status: experimental and community-driven with Sefaria backing and support. Sefaria owns the MIT-licensed toolkit, which began at Microsoft Global Hackathon 2026. Names and APIs may change.
Install public npm packages at exact version 0.1.0-alpha.0. The npm `alpha` tag moves between reviewed prereleases, not main-build snapshots. Browser examples pin the packaged standalone modules through jsDelivr; UNPKG is an explicit alternative, not an automatic fallback. Ordinary main CI publishes no packages or script snapshots.

Choose a path:

- To show Sefaria texts on a page, use the components from `@sefaria/web-components`. They're HTML elements, so prefer them to calling the API and handling Sefaria's text HTML yourself. For a page with no build step, add this script tag and element, then read https://sefaria.github.io/sefaria-frontend-toolkit/use-components/start-here:

```html
<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>
```

- To work with Sefaria's data in your own code, use `@sefaria/api-client` to fetch checked API responses and `@sefaria/text-transform` and its `normalizeText` function to make text HTML safe before you show it. Start at https://sefaria.github.io/sefaria-frontend-toolkit/data-and-text-tools/start-here.
- To install the npm packages, or to choose between them and the script tag, read https://sefaria.github.io/sefaria-frontend-toolkit/help/install-and-status. With a bundler, register every element once with `import "@sefaria/web-components";`. The element subpaths don't register their element.
- Keep attribution. For an attributed passage, including a bilingual one, use Source Card. Text Segment and Bilingual Segment show no attribution. Source Card shows each edition's title with its language name, linked to its source when the source is a valid http(s) address; don't hide it with `hide-attributions`, and don't copy text out of a component without its attribution. Reader also shows edition attribution. Only Source Card links it, and none of them shows a license. Connections Panel previews, also inside the Reader, can show "Licenses reported" when Sefaria provides them. See https://sefaria.github.io/sefaria-frontend-toolkit/help/install-and-status.html#license-and-text-rights.
- Source Card shows both the primary text and the translation by default (`content-language` defaults to `both`).
- Style the elements with the `--sefaria-*` settings listed at https://sefaria.github.io/sefaria-frontend-toolkit/reference/components.html#style-settings: `--sefaria-surface`, `--sefaria-surface-muted`, `--sefaria-fg`, `--sefaria-fg-muted`, `--sefaria-border`, `--sefaria-accent`, `--sefaria-link`, `--sefaria-panel-radius`, `--sefaria-control-radius`, `--sefaria-font-scale`, `--sefaria-font-hebrew`, `--sefaria-font-english`, `--sefaria-font-label-english`. Don't invent other names. You can also style an element's own box (`display`, `margin`, width), and the Reader exposes `::part(toolbar)`, `::part(history)`, `::part(source-pane)`, `::part(connections-pane)`. See https://sefaria.github.io/sefaria-frontend-toolkit/across-components/match-your-sites-look.html.
- If you're an assistant building a page for someone, also read https://sefaria.github.io/sefaria-frontend-toolkit/use-components/start-with-an-ai-assistant. Its prompt is at https://github.com/Sefaria/sefaria-frontend-toolkit/blob/main/examples/site-snippets/ai-assistant-prompt.md.
- For exact element, function, type and import names, use the reference pages below instead of guessing.

## Start here

- [Home](https://sefaria.github.io/sefaria-frontend-toolkit/): Drop in a tag to show a source, or use the JavaScript tools to fetch checked data and clean its text.
- [Use components › Start here](https://sefaria.github.io/sefaria-frontend-toolkit/use-components/start-here.html): Put your first Sefaria source on a page with two lines of HTML, or with a package import.
- [Use the data and text tools › Start here](https://sefaria.github.io/sefaria-frontend-toolkit/data-and-text-tools/start-here.html): Fetch a checked Sefaria response, clean Sefaria's HTML text, or do both, with runnable examples for Micah 6:8.
- [Use components › Start with an AI assistant](https://sefaria.github.io/sefaria-frontend-toolkit/use-components/start-with-an-ai-assistant.html): Give your AI coding assistant a copyable prompt so it builds a page with the toolkit's components, then check the result against a short list.
- [Help › Install and status](https://sefaria.github.io/sefaria-frontend-toolkit/help/install-and-status.html): Choose an install route, understand what alpha status means, and read the license and text rights.

## Use components

- [Use components › Show one passage](https://sefaria.github.io/sefaria-frontend-toolkit/use-components/show-text/show-one-passage.html): Show one passage of Sefaria text in the edition or translation you choose, and control vowel points and cantillation.
- [Use components › Show Hebrew and translation together](https://sefaria.github.io/sefaria-frontend-toolkit/use-components/show-text/hebrew-and-translation.html): Show a passage's primary text and a translation side by side or stacked, and choose the layout, order, language, and exact editions.
- [Use components › Show an attributed passage and let readers select it](https://sefaria.github.io/sefaria-frontend-toolkit/use-components/show-an-attributed-passage.html): Show a passage in a Source Card with its heading, both languages and attribution, and react when a reader selects a verse.
- [Use components › Use with a framework](https://sefaria.github.io/sefaria-frontend-toolkit/use-components/use-with-a-framework.html): Use the same Source Card and selection handler in plain JavaScript, React, or Alpine: which values are attributes, which are properties, and how to listen for events.
- [Use components › Show commentary and connected texts](https://sefaria.github.io/sefaria-frontend-toolkit/use-components/show-commentary-and-connected-texts.html): Show a text's commentaries and other connected texts in a Connections Panel, group them by category, and react when a reader chooses one.
- [Use components › Add the complete Reader](https://sefaria.github.io/sefaria-frontend-toolkit/use-components/add-the-complete-reader.html): Add the complete Reader, a finished reading surface with text, connections, history and a Back button, and add your own toolbar actions.
- [Across components › Match your site's look](https://sefaria.github.io/sefaria-frontend-toolkit/across-components/match-your-sites-look.html): Set colors, fonts, corner rounding, text size, and light or dark mode for every toolkit component at once, using shared --sefaria-* CSS properties.
- [Across components › Choose what text readers see](https://sefaria.github.io/sefaria-frontend-toolkit/across-components/choose-what-text-readers-see.html): Choose the translation, edition, Hebrew vocalization, and sides your readers see, and learn which choices make requests.
- [Across components › Make components respond to each other](https://sefaria.github.io/sefaria-frontend-toolkit/across-components/make-components-respond-to-each-other.html): Link two components so that selecting a verse in a Source Card updates a Connections Panel, using a state value in React or event listeners in plain JavaScript.

## Use the data and text tools

- [Use the data and text tools › Give components your own data](https://sefaria.github.io/sefaria-frontend-toolkit/data-and-text-tools/give-components-your-own-data.html): Render Sefaria components from data you already hold, or route their loading through your own source, so they don't request Sefaria from the browser.
- [Use the data and text tools › Handle errors in your code](https://sefaria.github.io/sefaria-frontend-toolkit/data-and-text-tools/handle-errors-in-your-code.html): Tell apart documented Sefaria errors, contract errors, and network or cancellation failures in your own code, and decide what to retry and what to report.
- [Use the data and text tools › Clean up stored Sefaria text](https://sefaria.github.io/sefaria-frontend-toolkit/data-and-text-tools/clean-up-stored-sefaria-text.html): See what normalizeText and the vocalization helpers change in stored Sefaria text, then combine them to prepare safe HTML, footnotes, and a chosen vowel level.

## Reference: exact names

- [Reference › Components](https://sefaria.github.io/sefaria-frontend-toolkit/reference/components.html): Attributes, properties, data, empty states, events and style settings for each Sefaria element.
- [Reference › Client](https://sefaria.github.io/sefaria-frontend-toolkit/reference/client.html): The client API of @sefaria/api-client, and its generated functions grouped by Sefaria's API sections.
- [Reference › Text tools](https://sefaria.github.io/sefaria-frontend-toolkit/reference/text-transform.html): The functions and types exported by @sefaria/text-transform, and the HTML that normalizeText produces.
- [Reference › Package imports and exports](https://sefaria.github.io/sefaria-frontend-toolkit/reference/package-imports-and-exports.html): The import paths of each toolkit package and the names each path exports.
- [Reference › Corrections to Sefaria's API description](https://sefaria.github.io/sefaria-frontend-toolkit/reference/api-corrections.html): Every correction the toolkit applies to Sefaria's API description before generating the client, grouped by endpoint.

## Concepts

- [Concepts › How the toolkit works](https://sefaria.github.io/sefaria-frontend-toolkit/concepts/how-the-toolkit-works.html): Follows one Source Card tag from your page to the screen: where its text comes from, how it is requested, how it is prepared, how it reports back, and how to do the same steps without components.
- [Concepts › The client and Sefaria's API](https://sefaria.github.io/sefaria-frontend-toolkit/concepts/the-client-and-sefarias-api.html): How the toolkit's client is generated from a pinned copy of Sefaria's API description, what it corrects and checks, and how its short-lived cache and drift check work.
- [Concepts › Clean text and safety](https://sefaria.github.io/sefaria-frontend-toolkit/concepts/clean-text-and-safety.html): Explains why Sefaria's text needs cleaning before it goes on a page, what normalizeText makes safe, why the vocalization helpers don't, and what your site still owns.
- [Concepts › Sefaria's own texts and tools](https://sefaria.github.io/sefaria-frontend-toolkit/concepts/sefarias-own-texts-and-tools.html): Learn what Sefaria means by a reference and an edition, how the toolkit picks a translation, and when Sefaria's own API, Linker, MCP servers, source sheets, or data exports fit better.

## Examples

- [Examples › Composed multi-pane Reader](https://sefaria.github.io/sefaria-frontend-toolkit/examples/composed-multi-pane-reader.html): An advanced example that puts several passages and their connections side by side by building on the Reader session instead of the complete Reader.
- [Examples › Linked article](https://sefaria.github.io/sefaria-frontend-toolkit/examples/linked-article.html): A complete app that previews a cited Sefaria source in a dialog when a reader clicks a link in your article, without leaving the page.
- [Examples › Reader inside AI chat](https://sefaria.github.io/sefaria-frontend-toolkit/examples/reader-inside-ai-chat.html): Show the Sefaria Reader inside an AI chat answer as an MCP App, with navigation that goes through the chat host instead of the browser.
- [Examples › This week's portion](https://sefaria.github.io/sefaria-frontend-toolkit/examples/this-weeks-portion.html): A complete app that asks Sefaria's calendar for this week's Torah portion and shows it on a Source Card, with no reference to edit by hand.

## Optional

- [Help › Troubleshoot a page](https://sefaria.github.io/sefaria-frontend-toolkit/help/troubleshoot-a-page.html): Match what you see on the page to its cause and fix, or get support.