@creativecreate/react-footnotes

A React component library for managing footnotes with citation and special symbol support.

Maintaining footnotes with proper numbering across different components and pages can be challenging — you need to manually track footnote order, handle duplicates, manage navigation between references and content, and ensure consistency throughout your application. Additionally, maintaining footnote content becomes difficult when footnotes are scattered across multiple files, making it hard to update or manage them centrally. This package tackles these challenges by providing a context-aware, automatic numbering system that handles everything for you. Use footnotes freely across any component without worrying about order or duplicates; the library automatically coordinates numbering, detects duplicates, and provides smart bidirectional navigation. With flexible content management through a centralized messages file, callback functions, or inline children, you can easily maintain and update footnote content regardless of where your components are located.

Features

- 📝 Support for both citation (numbered) and special (symbol) footnotes
- 🔄 Context-aware coordination and auto numbering: use footnotes freely across different components without manually tracking the order — the library handles everything automatically
- 🔁 Smart duplicate detection: multiple references to the same footnote automatically share the same number, preventing duplicate entries
- 🔗 Smart bidirectional navigation: navigate between footnote references and content, with intelligent tracking that traces back to the current reference location even when duplicate references exist
- 🎯 Flexible content sources: provide footnote content via messages file, callback function (getContent), or inline children — choose the approach that fits your needs
- 🌐 Framework-agnostic: Compatible with Next.js App Router (see integration guide), Remix, Vite, and other React frameworks
- ♿ Web accessibility compatible: built with ARIA attributes, semantic HTML, keyboard navigation support, and screen reader compatibility following WAI-ARIA best practices
- 🎨 Fully customizable with custom CSS to match your design style, with built-in responsive design support for all device sizes
- 📦 TypeScript support
- 🔄 Route-aware footnote reset for SPA navigation

Installation

``bash
npm install @creativecreate/react-footnotes
`

Next.js App Router

> ⚠️ Important for Next.js Users: This package uses React Context and requires a pathname prop, which means it requires client components. If you're using Next.js App Router, you may encounter server/client boundary errors. See our Next.js Integration Guide for detailed instructions on:
> - Setting up FootnoteProvider in layouts with automatic pathname handling
> - Handling server/client component boundaries
> - Managing the required pathname prop with Next.js hooks
> - Common errors and solutions (like createContext is not a function, usePathname() can only be used in Client Components)
> - Best practices for preserving server-side rendering

Quick Fix: If you see createContext is not a function errors, mark components using Footnote with 'use client' or extract the UI into a separate client component. For the pathname prop, use Next.js usePathname() and useSearchParams() hooks in a client component. See the Next.js guide for complete examples.

Basic Usage

$3

The package includes a messages.json file as a guideline/template. You should copy it to your project (e.g., to your src directory) and customize it with your own footnote content. You cannot import it directly from the package module.

Step 1: Copy messages.json from the package to your project (e.g., src/messages.json)

Step 2: Customize it with your footnote content:

`json
{
"footnotes": {
"citation": {
"smith-2023-study": "Smith, J., et al. 'Climate Change Impacts on Agriculture.' Nature Climate Change, vol. 13, no. 4, 2023, pp. 245-260.",
"who-guidelines": "World Health Organization. 'Air Quality Guidelines: Global Update 2021.' WHO Press, 2021.",
"johnson-research": "Johnson, M. 'Sustainable Energy Solutions.' Renewable Energy Journal, vol. 45, 2023, pp. 112-128."
},
"special": {
"editor-note": "Editor's note: This data was updated on March 15, 2024 to reflect the latest findings.",
"methodology-note": "Methodology: Survey conducted across 50 countries with a sample size of 10,000 participants."
}
}
}
`

Step 3: Import it from your project:

`tsx
import messagesData from './messages.json'; // Import from your project, not from the package

// Extract footnotes from the messages structure
const messages = messagesData.footnotes;
`

$3

`tsx
import { useState, useEffect } from 'react';
import { FootnoteProvider } from '@creativecreate/react-footnotes';
import messagesData from './messages.json'; // Your custom messages file from your project

// Extract footnotes from the messages structure
const messages = messagesData.footnotes;

function App() {
const [pathname, setPathname] = useState('');

useEffect(() => {
// Only access window on client-side
setPathname(${window.location.pathname}${window.location.search});
}, []);

return (
messages={messages}
// Alternative: see section - using React Router (recommended for SPAs)
pathname={pathname}
>
{/ Your app content /}

);
}
`

$3

`tsx
import { Footnote } from '@creativecreate/react-footnotes';

function MyComponent() {
return (



);
}
`

$3

`tsx
import { FootnoteList } from '@creativecreate/react-footnotes';

function Footer() {
return (



);
}
`

$3

You have two options for styling the footnotes:

Option A: Use the default stylesheet from the package

Import the default stylesheet to get pre-styled footnotes:

`tsx
import '@creativecreate/react-footnotes/footnotes.css';
`

Add this import in your main entry file (e.g., main.tsx, index.tsx, or _app.tsx for Next.js).

Option B: Use your own CSS with the available class names

If you prefer to style the footnotes yourself, you can target the following CSS classes in your own stylesheet:

`css
/ Footnote reference button (the clickable superscript in text) /
.footnote-ref { }
/ Footnote symbol (the number or symbol inside the button) /
.footnote-symbol { }
/ Footnote list (ordered list) /
.footnote-list { }
/ Individual footnote list item /
.footnote-list-item { }
/ Symbol in the list item /
.footnote-list-item__symbol { }
/ Footnote content in the list item /
.footnote-list-item__content { }
/ Back to reference link button /
.footnote-list-item__back-link { }
/ Back link icon /
.footnote-list-item__back-link-icon { }
`

You can also use the className props on components to apply your own custom classes (see Customizing Styles section for details).

Example output:

!Footnotes rendered in footer

Advanced Usage

$3

The getContent prop allows you to provide footnote content programmatically, overriding messages from the provider. This is useful for dynamic content or when you want to generate footnotes based on component state or props:

`tsx
import { Footnote } from '@creativecreate/react-footnotes';
import { useState, useEffect } from 'react';

function MyComponent() {
const [dynamicCitations, setDynamicCitations] = useState<{
citation?: { [key: string]: string };
special?: { [key: string]: string };
}>({});

useEffect(() => {
// Fetch citations asynchronously
fetchCitations().then(setDynamicCitations);
}, []);

// Custom function to generate footnote content
const getContent = (id: string, type: 'citation' | 'special') => {
if (type && id) {
return dynamicCitations[type]?.[id];
}
return null;
};

return (



);
}
`

When to use getContent:
- When footnote content depends on component state or props
- When you need to fetch content from an API or external source
- When you want to override provider messages for specific footnotes
- When content needs to be computed dynamically

$3

The children prop provides the highest priority for footnote content and allows you to pass content directly, including formatted text or React components:

`tsx
import { Footnote } from '@creativecreate/react-footnotes';
import {Link} from '~/components/Link';

function MyComponent() {
return (



);
}
`

When to use children:
- When you want to provide footnote content directly inline
- When you need to include formatted text or React components
- When content is specific to a single footnote instance
- When you want the highest priority (overrides both getContent and messages)

Priority order:
1. children prop (highest priority)
2. getContent prop
3. Messages from FootnoteProvider (lowest priority)

$3

`tsx
import { FootnoteList } from '@creativecreate/react-footnotes';

function MyPage() {
return (
className="my-custom-list-class" // Class for the

wrapper
itemClassName="my-item-class" // Class for each
1. item
itemSupClassName="my-sup-class" // Class for the symbol in items
itemContentClassName="my-content-class" // Class for the content in items
itemBackLinkClassName="my-back-link-class" // Class for the back link
itemBackLinkIconClassName="my-icon-class" // Class for the back link icon
order="citation-first" // Show citations before special footnotes
/>
);
}
`

   $3

   `tsx
import { Footnote } from '@creativecreate/react-footnotes';

   function MyComponent() {
return (


   
   

   
   This text has a customized footnote
   id="example1"
   type="citation"
   className="my-footnote-ref-class" // Class for the footnote reference

   
   supClassName="my-footnote-sup-class" // Class for the element
   />.