@wedgekit/toc

Description

A responsive Table of Contents component for tracking the currently viewed section based on scrolling

Installation

yarn add @wedgekit/toc

Note: In order to use @wedgekit/toc you must have installed react, react-dom and styled-components

Usage

The Toc component represents a responsive Table of Contents that responds to scrolling and focus.

Basic Implementation

import React from 'react';
import Toc from '@wedgekit/toc';
import styled from 'styled-components';

const AppContainer = styled.div`
  display: flex;
  flex-direction: row;
  flex: 1;
`;

const TocContainer = styled.div`
  margin-right: 8px;
`;

const ContentContainer = styled.div`
  max-height: 50vh;
  max-width: 400px;
  overflow-y: auto;
`;

const CenterContainer = styled.div`
  display: flex;
  flex-direction: row;
  justify-content: center;
  flex: 1;
`;

const StickyRight = styled.div`
  position: sticky;
  top: 0;
  right: 0;
`;

const Content = styled.p`
  white-space: normal;
`;

const content = `Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.`;

const App = () => {
  const containerRef = React.useRef(null);

  const sectionOneOneRef = React.useRef(null);
  const sectionOneTwoRef = React.useRef(null);
  const sectionOneThreeRef = React.useRef(null);
  const sectionOneFourRef = React.useRef(null);
  const sectionOneFiveRef = React.useRef(null);
  const sectionTwoOneRef = React.useRef(null);
  const sectionTwoTwoRef = React.useRef(null);
  const sectionTwoThreeRef = React.useRef(null);
  const sectionTwoFourRef = React.useRef(null);
  const sectionTwoFiveRef = React.useRef(null);

  const sections = [
    {
      sectionHeader: 'Section 1',
      subsections: [
        { title: 'Sub Section 1 1', ref: sectionOneOneRef },
        { title: 'Sub Section 1 2', ref: sectionOneTwoRef },
        { title: 'Sub Section 1 3', ref: sectionOneThreeRef },
        { title: 'Sub Section 1 4', ref: sectionOneFourRef },
        { title: 'Sub Section 1 5', ref: sectionOneFiveRef },
      ],
    },
    {
      sectionHeader: 'Section 2',
      subsections: [
        { title: 'Sub Section 2 1', ref: sectionTwoOneRef },
        { title: 'Sub Section 2 2', ref: sectionTwoTwoRef },
        { title: 'Sub Section 2 3', ref: sectionTwoThreeRef },
        { title: 'Sub Section 2 4', ref: sectionTwoFourRef },
        { title: 'Sub Section 2 5', ref: sectionTwoFiveRef },
      ],
    },
  ];

  return (
    <AppContainer>
      <CenterContainer>
        <ContentContainer ref={containerRef}>
          <div id="section-1-1" ref={sectionOneOneRef}>
            <h1>Section 1 1</h1>
            <Content>{content}</Content>
          </div>
          <div id="section-1-2" ref={sectionOneTwoRef}>
            <h1>Section 1 2</h1>
            <Content>
              {content}
              {content}
            </Content>
          </div>
          <div id="section-1-3" ref={sectionOneThreeRef}>
            <h1>Section 1 3</h1>
            <Content>
              {content}
              {content}
            </Content>
          </div>
          <div id="section-1-4" ref={sectionOneFourRef}>
            <h1>Section 1 4</h1>
            <Content>
              {content}
              {content}
            </Content>
          </div>
          <div id="section-1-5" ref={sectionOneFiveRef}>
            <h1>Section 1 5</h1>
            <Content>
              {content}
              {content}
            </Content>
          </div>
          <div id="section-2-1" ref={sectionTwoOneRef}>
            <h1>Section 2 1</h1>
            <Content>{content}</Content>
          </div>
          <div id="section-2-2" ref={sectionTwoTwoRef}>
            <h1>Section 2 2</h1>
            <Content>{content}</Content>
          </div>
          <div id="section-2-3" ref={sectionTwoThreeRef}>
            <h1>Section 2 3</h1>
            <Content>
              {content}
              {content}
              {content}
              {content}
            </Content>
          </div>
          <div id="section-2-4" ref={sectionTwoFourRef}>
            <h1>Section 2 4</h1>
            <Content>{content}</Content>
          </div>
          <div id="section-2-5" ref={sectionTwoFiveRef}>
            <h1>Section 2 5</h1>
            <Content>
              {content}
              {content}
              {content}
            </Content>
          </div>
        </ContentContainer>
        <TocContainer>
          <StickyRight>
            <Toc containerRef={containerRef} sections={sections} />
          </StickyRight>
        </TocContainer>
      </CenterContainer>
    </AppContainer>
  );
};

render(<App />);

Props

activeSectionRef

Refs provide access to the underlying DOM element.

Type: RefObject<HTMLDivElement>

Required: ❌

A roving ref that always points to the div containing the active section title and indicator

className

Type: string

Required: ❌

This is exposed but is only here so that styled-components will be able to style components correctly. Please do not use this unless you really know what you are doing.

containerRef

Type: RefObject<HTMLDivElement>

Refs provide access to the underlying DOM element.

Required: ✅

The ref to the div that holds all of the content. This is used to scroll when pressing on a section in the Toc.

domain

Type: 'default' | 'light' | 'dark'

Required: ❌

A string denoting the domain the Toc is used for. This defaults to 'default'.

extraScrollOffset

Type: number

Required: ❌

Number of pixels to remove from the the full viewport height. This is used to help with the auto scrolling when the toc is not allowed to be the full size of the viewport.

sections

Type: { sectionHeader: string; subsections: { title: string; ref: RefObject<HTMLDivElement> }[]; }[];

Required: ✅

The sections to display in the Table of contents

throttleTime

Type: number

Required: ❌

The time to throttle the scroll listener for, defaults to 200ms