{"id":15620770,"url":"https://github.com/kittygiraudel/react-a11y-footnotes","last_synced_at":"2025-10-08T20:26:11.200Z","repository":{"id":37987671,"uuid":"315005960","full_name":"KittyGiraudel/react-a11y-footnotes","owner":"KittyGiraudel","description":"A reusable React implementation of accessible footnotes.","archived":false,"fork":false,"pushed_at":"2025-04-01T07:07:50.000Z","size":3866,"stargazers_count":36,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T08:48:59.413Z","etag":null,"topics":["a11y","accessibility","component","footnotes","react"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KittyGiraudel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-22T09:57:25.000Z","updated_at":"2025-04-01T07:07:52.000Z","dependencies_parsed_at":"2024-07-15T13:59:05.926Z","dependency_job_id":"e0751b1e-b152-48e0-a181-60729e5f1b28","html_url":"https://github.com/KittyGiraudel/react-a11y-footnotes","commit_stats":{"total_commits":283,"total_committers":6,"mean_commits":"47.166666666666664","dds":"0.21201413427561833","last_synced_commit":"3231aae176682b9122e3043698d5f6c36b9fc592"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KittyGiraudel%2Freact-a11y-footnotes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KittyGiraudel%2Freact-a11y-footnotes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KittyGiraudel%2Freact-a11y-footnotes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KittyGiraudel%2Freact-a11y-footnotes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KittyGiraudel","download_url":"https://codeload.github.com/KittyGiraudel/react-a11y-footnotes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036063,"owners_count":21037092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a11y","accessibility","component","footnotes","react"],"created_at":"2024-10-03T09:02:28.526Z","updated_at":"2025-10-08T20:26:06.150Z","avatar_url":"https://github.com/KittyGiraudel.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-a11y-footnotes\n\nreact-a11y-dialog is a thin React component to ease the use of accessible footnotes in React applications. This implementation is heavily inspired by [Accessible footnotes with CSS](https://www.sitepoint.com/accessible-footnotes-css/).\n\nFind a [complete demo on CodeSandbox](https://codesandbox.io/s/react-a11y-footnotes-f9lpdy).\n\n- [Install](#install)\n- [Terminology](#terminology)\n- [Usage](#usage)\n- [API](#api)\n  - [`FootnotesProvider`](#footnotesprovider)\n  - [`FootnoteRef`](#footnoteref)\n  - [`Footnotes`](#footnotes)\n- [Styling](#styling)\n  - [Using base styles](#using-base-styles)\n    - [With a bundler](#with-a-bundler)\n    - [Without a bundler](#with-a-bundler)\n  - [Customisation](#customisation)\n    - [With CSS](#with-css)\n    - [With CSS-in-JS](#with-css-in-js)\n- [ID generation](#id-generation)\n- [Example](#example)\n\n## Install\n\n```sh\nnpm install react-a11y-footnotes\n```\n\n## Terminology\n\n- **Footnotes**: the additional information present at the bottom of a content area using footnote references.\n- **Footnote reference**: a text segment offering more information in the footnotes.\n\n![Footnotes](./terminology.png)\n\n## Usage\n\nThe library exports 3 parts, all necessary to make everything work correctly:\n\n- `FootnotesProvider`: a component with no HTML footprint, that needs to wrap the content part of your application.\n- `FootnoteRef`: an inline component wrapping a footnote reference, rendering an anchor link (`\u003ca\u003e`) to the correct footnote in the footer.\n- `Footnotes`: a component rendering the actual footnotes, usually placed at the end of the content area.\n\n## API\n\n### `FootnotesProvider`\n\nThe `footnotesTitleId` prop can be passed to customise the `id` attribute assigned to the title rendered by `Footnotes` and referenced in every singled `FootnoteRef`.\n\nIf you are going to customise the `Title` prop from `Footnotes`, make sure to render `props.id` in the DOM, as this is how the value of `footnotesTitleId` is mapped between the references and the footnotes.\n\n### `FootnoteRef`\n\nThe `FootnoteRef` renders a link like this:\n\n```html\n\u003ca\n  id=\"css-counters-ref\"\n  href=\"#css-counters-note\"\n  aria-describedby=\"footnotes-label\"\n  role=\"doc-noteref\"\n  \u003eCSS counters\u003c/a\n\u003e\n```\n\n- The `description` prop is mandatory and contains the content of the footnote. It can be a string or a React tree.\n- The `id` prop can be passed to handle `id` manually, otherwise it is automatically generated from the reference content.\n- The `style` and `className` props can be freely passed through in order to enable styling with CSS-in-JS libraries (see [Styling](#styling) section).\n\nAs you can see, the footnote reference itself does not contain a number (e.g. `[1]`) on an asterisk (`*`). This is done in CSS with pseudo-elements. If CSS does not render, the links still work and the footnotes still make sense, no big deal.\n\n### `Footnotes`\n\nThe `Footnotes` component renders a HTML structure like this:\n\n```html\n\u003cfooter role=\"doc-endnotes\"\u003e\n  \u003ch2 id=\"footnotes-label\"\u003eFootnotes\u003c/h2\u003e\n  \u003col\u003e\n    \u003cli id=\"css-counters-note\"\u003e\n      CSS counters are, in essence, variables maintained by CSS whose values may\n      be incremented by CSS rules to track how many times they’re used.\n      \u003ca\n        href=\"#css-counters-ref\"\n        aria-label=\"Back to reference 1\"\n        role=\"doc-backlink\"\n        \u003e↩\u003c/a\n      \u003e\n    \u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/footer\u003e\n```\n\n- The `Wrapper` prop can be passed to customise the wrapper. It is `'footer'` by default to render a `\u003cfooter\u003e` HTML element, and can accept any React component. This wrapper is technically not mandatory and could be replaced with a `React.Fragment`.\n\n- The `Title` prop can be passed to customise the title. It is `props =\u003e \u003ch2 {...props}\u003eFootnotes\u003c/h2\u003e` by default to render a title level 2 named “Footnotes”, and can accept any React component. This component can be [visually hidden](https://hugogiraudel.com/2016/10/13/css-hide-and-seek/) but **it should still be present accessible**!\n\n- The `List` prop can be passed to customise the list. It is `'ol'` by default to render a `\u003col\u003e` HTML element, and can accept any React component.\n\n- The `ListItem` prop can be passed to customise the list. It is `'li'` by default to render a `\u003cli\u003e` HTML element, and can accept any React component.\n\n- The `BackLink` prop can be passed to customise the link back to the reference with each list item. It is `props =\u003e \u003ca {...props}\u003e↩\u003c/a\u003e` by default to render a link containing `↩`, and can accepted any component.\n\n## Styling\n\nStyling is left at the description of the author. That being said, some very basic styling are packaged with the library and can be used if deemed necessary.\n\n### Using base styles\n\n#### With a bundler\n\nIf you are using a module bundler like webpack or parcel, you can import them where you import the component.\n\n```js\n// Import the components\nimport { FootnotesProvider, FootnoteRef, Footnotes } from 'react-a11y-footnotes'\n\n// And the styles\nimport 'react-a11y-footnotes/dist/styles.css'\n```\n\n#### Without a bundler\n\nIf you’re not using a bundler you can find the styles at:\n\n```\nyour-app/node_modules/react-a11y-footnotes/dist/styles.css\n```\n\nInclude this file however you include the rest of your stylesheets. Alternatively, you can use a CDN like Unpkg, but this is not recommended for production apps.\n\n```html\n\u003clink\n  rel=\"stylesheet\"\n  type=\"text/css\"\n  href=\"https://unpkg.com/react-a11y-footnotes@\u003cversion\u003e/dist/styles.css\"\n/\u003e\n```\n\n### Overriding and customisation\n\n#### With CSS\n\nThe library provides namespaced data attributes as styling anchors:\n\n- `data-a11y-footnotes-ref`: applied to every single footnote reference\n- `data-a11y-footnotes-footer`: applied to the footnotes wrapper\n- `data-a11y-footnotes-title`: applied to the footnotes title\n- `data-a11y-footnotes-list`: applied to the footnotes list\n- `data-a11y-footnotes-list-item`: applied to every individual footnote\n- `data-a11y-footnotes-back-link`: applied to every individual back link\n\n#### With CSS-in-JS\n\nGiven every component rendered by the `Footnotes` component is customisable, and `FootnoteRef` accept both `style` and `className`, integration with CSS-in-JS libraries should be relatively seamless.\n\nFor instance, the `FootnoteRef` could be wrapped as such with [Fela](https://fela.js.org):\n\n```js\nconst refStyles = () =\u003e ({ color: 'deeppink' })\nconst Ref = createComponentWithProxy(refStyles, FootnoteRef)\n```\n\nAnd with [styled-components](https://styled-components.com):\n\n```js\nconst Ref = styled(FootnoteRef)`\n  color: deeppink;\n`\n```\n\n## ID generation\n\nFor a reference to link to its relevant footnote, and for the latter to provide a link back to the reference, there is an automatic system for resolving identifiers—regardless whether `id` is passed to the reference or not.\n\nConsider a reference which receives an `id` prop named `foobar` (`\u003cFootnoteRef id=\"foobar\"\u003e`). The underlying anchor element will actually receive `foobar-ref` as an `id` (`\u003ca id=\"foobar-ref\"\u003e`). Similarly, the relevant footnote will receive `foobar-note` as an `id` (`\u003cli id=\"foobar-note\"\u003e`). This behaviour cannot be changed.\n\nIf no `id` is passed to references (`\u003cFootnoteRef\u003e`)—which is usually the case—the `id` will be computed from the content of the reference. For instance if the text says “CSS counters”, the resolved identifiers will be `css-counters-ref` and `css-counters-note`.\n\n## Example\n\nFind a [complete demo on CodeSandbox](https://codesandbox.io/s/react-a11y-footnotes-f9lpdy).\n\n```js\nimport {\n  FootnotesProvider,\n  FootnoteRef as Ref,\n  Footnotes,\n} from 'react-a11y-footnotes'\n\nconst YourComponent = props =\u003e {\n  return (\n    \u003cFootnotesProvider\u003e\n      \u003cp\u003e\n        Maintaining{' '}\n        \u003cRef description='Footnotes are notes placed at the bottom of a page. They cite references or comment on a designated part of the text above it.'\u003e\n          footnotes\n        \u003c/Ref\u003e{' '}\n        manually can be a pain. By using{' '}\n        \u003cRef description='Cascading Style Sheets'\u003eCSS\u003c/Ref\u003e{' '}\n        \u003cRef\n          id='with-a-custom-id'\n          description={\n            \u003c\u003e\n              \u003ca\n                href='https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Lists_and_Counters/Using_CSS_counters'\n                target='_blank'\n                rel='noopener noreferrer'\n              \u003e\n                CSS counters\n              \u003c/a\u003e{' '}\n              are, in essence, variables maintained by CSS whose values may be\n              incremented by CSS rules to track how many times they’re used.\n            \u003c/\u003e\n          }\n        \u003e\n          counters\n        \u003c/Ref\u003e{' '}\n        to add the numbered references in the text and an ordered list to\n        display the actual footnotes in the footer, it becomes extremely easy.\n      \u003c/p\u003e\n\n      \u003cFootnotes /\u003e\n    \u003c/FootnotesProvider\u003e\n  )\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkittygiraudel%2Freact-a11y-footnotes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkittygiraudel%2Freact-a11y-footnotes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkittygiraudel%2Freact-a11y-footnotes/lists"}