React Footnote System

A fully featured, customizable, and accessible footnote management system for React applications. Provides automatic numbering, context-based management, and flexible rendering with TypeScript support for modern web development.

✨ Core Features

• 🔢 Automatic Numbering – smart footnote numbering with context awareness
• 📝 Context Management – centralized footnote state across components
• 🎯 Flexible Rendering – customizable footnote references and lists
• ⚡ TypeScript Support – comprehensive type definitions included
• 🎨 Customizable Styling – complete visual customization options
• ♿ Accessible – ARIA support and semantic HTML structure
• 🔄 Dynamic Registration – footnotes register automatically when mounted
• 📱 Responsive Design – works seamlessly across all device sizes

📦 Installation

npm install "@harshiniravikumar/react-footnote-system"

🔧 Main Components

| Component | Type | Description | |-----------|------|-------------| | FootnoteContext | Provider | Context provider for footnote management | | FootnoteReference | Component | Creates footnote references with automatic numbering | | FootnoteList | Component | Renders all registered footnotes in list format | | Footnote | Component | Standalone footnote component for advanced use cases |

🎯 Component Props

FootnoteReference

| Prop | Type | Default | Description | |------|------|---------|-------------| | id | string | - | Unique identifier for the footnote (required) | | children | ReactNode | - | The footnote content | | className | string | '' | Additional CSS classes for the reference | | onClick | () => void | - | Custom click handler | | style | CSSProperties | {} | Inline styles for the reference | | renderReference | (number: number) => ReactNode | - | Custom reference renderer |

FootnoteList

| Prop | Type | Default | Description | |------|------|---------|-------------| | className | string | '' | CSS classes for the list container | | itemClassName | string | '' | CSS classes for footnote items | | title | string | "Footnotes" | Title for the footnote section | | showTitle | boolean | true | Whether to display the title | | orderBy | "appearance" \| "alphabetical" | "appearance" | Footnote ordering method | | renderItem | (footnote: FootnoteData) => ReactNode | - | Custom footnote item renderer |

Footnote

| Prop | Type | Default | Description | |------|------|---------|-------------| | id | string | - | Unique identifier (required) | | content | string \| ReactNode | - | Footnote content | | number | number | - | Manual footnote number override | | autoRegister | boolean | true | Automatically register with context |

⚙️ Footnote Context Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | startNumber | number | 1 | Starting number for footnote numbering | | numberingStyle | "numeric" \| "roman" \| "alpha" | "numeric" | Numbering style for footnotes | | allowDuplicates | boolean | false | Allow duplicate footnote IDs | | resetOnUnmount | boolean | false | Reset footnotes when context unmounts | | maxFootnotes | number | undefined | Maximum number of footnotes allowed |

🎨 Theme Configuration

Customize the visual appearance of your footnotes:

const footnoteTheme = {
  reference: {
    color: "#007bff",
    fontSize: "0.8em",
    verticalAlign: "super",
    textDecoration: "none",
    padding: "0 2px",
    borderRadius: "2px",
    backgroundColor: "transparent"
  },
  list: {
    borderTop: "1px solid #e0e0e0",
    marginTop: "2rem",
    paddingTop: "1rem",
    fontSize: "0.9em"
  },
  item: {
    marginBottom: "0.5rem",
    lineHeight: "1.4",
    color: "#666"
  },
  title: {
    fontSize: "1.1em",
    fontWeight: "bold",
    marginBottom: "1rem",
    color: "#333"
  }
};

🖼️ Basic Usage

import React from 'react';
import { 
  FootnoteContext, 
  FootnoteReference, 
  FootnoteList 
} from "@your-username/react-footnote-system";

function BasicExample() {
  return (
    <FootnoteContext>
      <article>
        <h1>Article Title</h1>
        <p>
          This is some content with a footnote
          <FootnoteReference id="note1">
            This appears as footnote #1 at the bottom of the page.
          </FootnoteReference>
          and more text continues here.
        </p>
        
        <p>
          Another paragraph with another reference
          <FootnoteReference id="note2">
            This becomes footnote #2 with automatic numbering.
          </FootnoteReference>
          in the middle of the sentence.
        </p>

        <FootnoteList />
      </article>
    </FootnoteContext>
  );
}

🔮 Advanced Usage with All Features

import React, { useRef, useContext } from 'react';
import { 
  FootnoteContext, 
  FootnoteReference, 
  FootnoteList,
  useFootnoteContext 
} from "@your-username/react-footnote-system";

function AdvancedExample() {
  const footnoteContext = useFootnoteContext();

  const handleFootnoteClick = (id: string) => {
    console.log('Footnote clicked:', id);
  };

  return (
    <FootnoteContext
      options={{
        startNumber: 1,
        numberingStyle: "numeric",
        allowDuplicates: false,
        resetOnUnmount: true,
        maxFootnotes: 50
      }}
      theme={{
        reference: {
          color: "#0066cc",
          backgroundColor: "#f0f8ff",
          borderRadius: "4px",
          padding: "2px 4px"
        },
        list: {
          borderTop: "2px solid #0066cc",
          backgroundColor: "#fafafa"
        }
      }}
    >
      <main>
        <section>
          <h1>Research Paper</h1>
          <p>
            Recent studies show significant findings
            <FootnoteReference 
              id="study-2024"
              onClick={() => handleFootnoteClick("study-2024")}
              className="custom-reference"
            >
              Smith, J., & Johnson, A. (2024). "Advanced Research Methods in Modern Science." 
              <em>Journal of Scientific Discovery</em>, 42(3), 123-145. 
              DOI: 10.1000/journal.2024.123
            </FootnoteReference>
            that support our hypothesis.
          </p>

          <p>
            The methodology employed
            <FootnoteReference id="methodology">
              Our research methodology followed the guidelines established by 
              the International Research Standards Committee (IRSC).
            </FootnoteReference>
            ensures reliable results across multiple scenarios.
          </p>
        </section>

        <footer>
          <FootnoteList 
            title="References & Notes"
            className="research-footnotes"
            itemClassName="footnote-item"
            showTitle={true}
            orderBy="appearance"
            renderItem={(footnote) => (
              <div className="custom-footnote">
                <span className="footnote-number">{footnote.number}.</span>
                <span className="footnote-content">{footnote.content}</span>
              </div>
            )}
          />
        </footer>
      </main>
    </FootnoteContext>
  );
}

📱 Multiple Contexts & Sections

function MultiSectionDocument() {
  return (
    <div>
      {/* Chapter 1 with independent footnotes */}
      <FootnoteContext options={{ startNumber: 1 }}>
        <section>
          <h2>Chapter 1: Introduction</h2>
          <p>
            Content with footnotes
            <FootnoteReference id="ch1-intro">
              Introduction footnote content here.
            </FootnoteReference>
            specific to this chapter.
          </p>
          <FootnoteList title="Chapter 1 Notes" />
        </section>
      </FootnoteContext>

      <FootnoteContext options={{ startNumber: 1, numberingStyle: "roman" }}>
        <section>
          <h2>Chapter 2: Methodology</h2>
          <p>
            Different chapter content
            <FootnoteReference id="ch2-method">
              Methodology footnote with roman numerals.
            </FootnoteReference>
            with separate footnote numbering.
          </p>
          <FootnoteList title="Chapter 2 Notes" />
        </section>
      </FootnoteContext>
    </div>
  );
}

🎬 Custom Renderers & Animations

function CustomFootnoteExample() {
  return (
    <FootnoteContext>
      <div>
        <p>
          Text with custom reference
          <FootnoteReference 
            id="custom"
            renderReference={(number) => (
              <span className="custom-ref">
                [{number}]
              </span>
            )}
          >
            Custom styled footnote content
          </FootnoteReference>
        </p>

        <FootnoteList 
          renderItem={(footnote) => (
            <div className="animated-footnote">
              <strong>{footnote.number}.</strong>
              <span>{footnote.content}</span>
            </div>
          )}
        />
      </div>
    </FootnoteContext>
  );
}

🔄 Callbacks & Events

| Callback | Type | Description | |----------|------|-------------| | onFootnoteRegister | (id: string, content: ReactNode) => void | Called when footnote is registered | | onFootnoteUnregister | (id: string) => void | Called when footnote is unregistered | | onFootnoteClick | (id: string, number: number) => void | Called when footnote reference is clicked | | onListRender | (footnotes: FootnoteData[]) => void | Called when footnote list renders | | onMaxFootnotesReached | () => void | Called when max footnotes limit is reached |

🛠️ Hook: useFootnoteContext

Access footnote context methods and state:

| Method/Property | Type | Description | |-----------------|------|-------------| | footnotes | FootnoteData[] | Array of all registered footnotes | | register | (id: string, content: ReactNode) => void | Register a new footnote | | unregister | (id: string) => void | Unregister a footnote | | getFootnote | (id: string) => FootnoteData \| undefined | Get footnote by ID | | getFootnoteNumber | (id: string) => number \| undefined | Get footnote number by ID | | reset | () => void | Clear all footnotes | | count | number | Total number of registered footnotes |

import { useFootnoteContext } from "@your-username/react-footnote-system";

function FootnoteStats() {
  const { footnotes, count, reset } = useFootnoteContext();
  
  return (
    <div>
      <p>Total footnotes: {count}</p>
      <button onClick={reset}>Clear All Footnotes</button>
    </div>
  );
}

🎯 Real-World Examples

Academic Paper

<FootnoteContext options={{ numberingStyle: "numeric" }}>
  <article className="academic-paper">
    <h1>The Impact of Climate Change on Marine Ecosystems</h1>
    <p>
      Recent oceanographic studies
      <FootnoteReference id="ocean-study-2024">
        Martinez, C., et al. (2024). "Ocean Temperature Variations and Marine Biodiversity." 
        <em>Marine Biology Quarterly</em>, 78(2), 45-67.
      </FootnoteReference>
      indicate significant temperature variations in coastal waters.
    </p>
    
    <p>
      These findings corroborate earlier research
      <FootnoteReference id="previous-research">
        See Thompson, R. (2022) and Williams, S. (2023) for comprehensive 
        reviews of historical temperature data.
      </FootnoteReference>
      from the past decade.
    </p>

    <FootnoteList title="References" className="academic-references" />
  </article>
</FootnoteContext>

Blog Post with Explanatory Notes

<FootnoteContext options={{ numberingStyle: "alpha" }}>
  <article className="blog-post">
    <h1>Understanding React Hooks</h1>
    <p>
      React Hooks revolutionized functional components
      <FootnoteReference id="hooks-intro">
        Hooks were introduced in React 16.8 (February 2019) and allow you to 
        use state and other React features in functional components.
      </FootnoteReference>
      by enabling state management without classes.
    </p>

    <p>
      The useState hook
      <FootnoteReference id="usestate-example">
        <code>const [state, setState] = useState(initialValue)</code> is the 
        most commonly used hook for managing component state.
      </FootnoteReference>
      is fundamental to modern React development.
    </p>

    <FootnoteList 
      title="Additional Information" 
      className="blog-footnotes"
      showTitle={true}
    />
  </article>
</FootnoteContext>

Legal Document with Roman Numerals

<FootnoteContext options={{ numberingStyle: "roman" }}>
  <div className="legal-document">
    <h1>Terms of Service</h1>
    <section>
      <h2>Section 1: Definitions</h2>
      <p>
        "Service" refers to the platform
        <FootnoteReference id="service-definition">
          As defined under applicable consumer protection laws and regulations 
          in the jurisdiction where the service is provided.
        </FootnoteReference>
        provided by the Company.
      </p>
    </section>

    <FootnoteList 
      title="Legal References"
      className="legal-footnotes"
      itemClassName="legal-footnote-item"
    />
  </div>
</FootnoteContext>

🎨 Custom Styling Examples

Modern Glass Effect

.modern-footnotes .footnote-reference {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
  border-radius: 6px;
  padding: 2px 6px;
  color: #007bff;
  text-decoration: none;
  transition: all 0.2s ease;
}

.modern-footnotes .footnote-reference:hover {
  background: rgba(255, 255, 255, 0.2);
  transform: translateY(-1px);
}

.modern-footnotes .footnote-list {
  background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%);
  border-radius: 12px;
  padding: 1.5rem;
  margin-top: 2rem;
}

Academic Style

.academic-footnotes .footnote-reference {
  color: #d32f2f;
  font-weight: 500;
  vertical-align: super;
  font-size: 0.75em;
  text-decoration: none;
  border-bottom: 1px dotted #d32f2f;
}

.academic-footnotes .footnote-list {
  border-top: 2px solid #333;
  margin-top: 3rem;
  padding-top: 1rem;
  font-family: 'Times New Roman', serif;
}

.academic-footnotes .footnote-item {
  text-indent: -1em;
  padding-left: 1em;
  margin-bottom: 0.8rem;
}

📱 Responsive Behavior

function ResponsiveFootnotes() {
  return (
    <FootnoteContext>
      <div className="responsive-content">
        <p>
          Mobile-optimized footnotes
          <FootnoteReference 
            id="mobile-note"
            className="responsive-reference"
          >
            On mobile devices, footnotes adapt to smaller screens with 
            optimized touch targets and readable font sizes.
          </FootnoteReference>
          work seamlessly across devices.
        </p>

        <FootnoteList className="responsive-footnote-list" />
      </div>
    </FootnoteContext>
  );
}

@media (max-width: 768px) {
  .responsive-reference {
    font-size: 0.9em !important;
    padding: 4px 6px !important;
  }
  
  .responsive-footnote-list {
    font-size: 0.85em;
    padding: 1rem 0.5rem;
  }
}

♿ Accessibility Features

• ARIA Labels: Proper labeling for screen readers
• Keyboard Navigation: Tab and Enter key support
• Semantic HTML: Uses appropriate HTML elements
• High Contrast: Works with high contrast modes
• Screen Reader Support: Announces footnote numbers and content
• Focus Management: Proper focus indicators and management

<FootnoteReference 
  id="accessible-note"
  aria-label="Footnote reference 1"
  role="doc-noteref"
>
  Accessible footnote content
</FootnoteReference>

🚀 Performance Features

• Lazy Registration: Footnotes register only when needed
• Efficient Re-renders: Optimized with React.memo and context optimization
• Memory Management: Automatic cleanup on unmount
• Minimal Bundle Size: Tree-shakeable components
• No Dependencies: Pure React implementation

📄 TypeScript Support

Comprehensive TypeScript definitions included:

import type { 
  Footnotes,
  FootnoteProps,
  FootnoteContextType,
  FootnoteRefProps,
  FootnoteListProps,
  FootnoteData,
  FootnoteOptions,
  FootnoteTheme
} from "@your-username/react-footnote-system";

interface CustomFootnoteData {
  id: string;
  content: string;
  category: 'reference' | 'explanation' | 'source';
}

const MyComponent: React.FC = () => {
  const [footnotes, setFootnotes] = useState<CustomFootnoteData[]>([]);
  
  return (
    <FootnoteContext>
      {/* Your footnote implementation */}
    </FootnoteContext>
  );
};

🔧 Configuration Examples

Numbered Footnotes (Default)

<FootnoteContext options={{ numberingStyle: "numeric" }}>
  {/* Footnotes appear as: 1, 2, 3, ... */}
</FootnoteContext>

Roman Numeral Footnotes

<FootnoteContext options={{ numberingStyle: "roman" }}>
  {/* Footnotes appear as: i, ii, iii, ... */}
</FootnoteContext>

Alphabetical Footnotes

<FootnoteContext options={{ numberingStyle: "alpha" }}>
  {/* Footnotes appear as: a, b, c, ... */}
</FootnoteContext>

Custom Starting Number

<FootnoteContext options={{ startNumber: 10 }}>
  {/* Footnotes start from: 10, 11, 12, ... */}
</FootnoteContext>

🎪 Interactive Examples

Footnotes with Custom Actions

function InteractiveFootnotes() {
  const [selectedFootnote, setSelectedFootnote] = useState<string | null>(null);

  return (
    <FootnoteContext>
      <div>
        <p>
          Click this footnote
          <FootnoteReference 
            id="interactive"
            onClick={() => setSelectedFootnote("interactive")}
          >
            This footnote has custom click behavior and can trigger actions 
            in your application.
          </FootnoteReference>
          to see custom behavior.
        </p>

        {selectedFootnote && (
          <div className="footnote-popup">
            <p>You clicked footnote: {selectedFootnote}</p>
            <button onClick={() => setSelectedFootnote(null)}>Close</button>
          </div>
        )}

        <FootnoteList />
      </div>
    </FootnoteContext>
  );
}

Dynamic Footnote Management

function DynamicFootnotes() {
  const { register, unregister, footnotes, reset } = useFootnoteContext();

  const addDynamicFootnote = () => {
    const id = `dynamic-${Date.now()}`;
    register(id, `Dynamic footnote added at ${new Date().toLocaleTimeString()}`);
  };

  return (
    <div>
      <button onClick={addDynamicFootnote}>Add Footnote</button>
      <button onClick={reset}>Clear All</button>
      <p>Current footnotes: {footnotes.length}</p>
      <FootnoteList />
    </div>
  );
}

🔮 Integration with Other Libraries

With Markdown Processors

import ReactMarkdown from 'react-markdown';

function MarkdownWithFootnotes({ content }: { content: string }) {
  return (
    <FootnoteContext>
      <ReactMarkdown 
        components={{
          sup: ({ children }) => (
            <FootnoteReference id={`md-${children}`}>
              Markdown footnote content
            </FootnoteReference>
          )
        }}
      >
        {content}
      </ReactMarkdown>
      <FootnoteList />
    </FootnoteContext>
  );
}

With Content Management Systems

function CMSContent({ content }: { content: any[] }) {
  return (
    <FootnoteContext>
      {content.map((block, index) => {
        if (block.type === 'footnote') {
          return (
            <FootnoteReference key={index} id={block.id}>
              {block.content}
            </FootnoteReference>
          );
        }
        return <div key={index}>{block.content}</div>;
      })}
      <FootnoteList />
    </FootnoteContext>
  );
}

🧪 Testing Support

import { render, screen } from '@testing-library/react';
import { FootnoteContext, FootnoteReference, FootnoteList } from 'your-library';

test('footnotes render correctly', () => {
  render(
    <FootnoteContext>
      <FootnoteReference id="test">Test footnote</FootnoteReference>
      <FootnoteList />
    </FootnoteContext>
  );
  
  expect(screen.getByText('1')).toBeInTheDocument();
  expect(screen.getByText('Test footnote')).toBeInTheDocument();
});

📄 License

MIT License - feel free to use in your projects!