TelescopicText

TelescopicText is a React component inspired by telescopictext.org and the principles outlined in Howard Rheingold's seminal work, Tools for Thought. It embodies the idea of creating tools that extend our ability to explore, express, and communicate complex ideas interactively.

By enabling text to progressively expand and reveal layers of meaning, TelescopicText serves as both a creative medium and a thinking tool. It’s perfect for crafting educational content, interactive stories, or interfaces that prioritize clarity and discovery, turning text into an evolving and interactive experience.

Table of Contents

1. Installation
2. Usage Example
3. Props
4. TelescopicItem Type
5. Local Storage / Persistence
6. Styling
7. Advanced Usage
8. License

Installation

Install via your favorite package manager (NPM, Yarn, or PNPM):

npm install @telescopic-text/react

Or with Yarn:

yarn add @telescopic-text/react

or with PNPM:

pnpm add @telescopic-text/react

Usage Example

import React from "react";
import TelescopicText from "@telescopic-text/react";

const MyComponent: React.FC = () => {
const data = [
  "Once upon a time, ",
  {
    word: "in the mountain range",
    expandTo: [
      "in the heart of a misty mountain range, there lived a ",
      {
        word: "dragon named Ignis",
        expandTo: [
          "dragon named Ignis. His shimmering scales glinted like molten gold in the sunlight, and his breath was a searing inferno capable of turning stone to ash."
        ]
      },
    ]
  },
  " Ignis dwelled in a cavern ",
  {
    word: "so deep.",
    expandTo: [
      "so deep and vast that it echoed with the whispers of ancient winds and the soft hum of magic."
    ]
  },
];

  return (
    <div>
      <h1>Telescopic Text Demo</h1>
      <TelescopicText nodes={data} />
    </div>
  );
};

export default MyComponent;

Props

| Prop | Type | Default | Description | |-----------------------|--------------------------------------------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | nodes | TelescopicItem[] | (required) | The top-level array of items to render. Each item can be a string, a React node, or a TelescopicTextNodeData object. | | persistenceKey? | string | "telescopic-text" | A key to store the user’s expand/collapse state in localStorage. | | enablePersistence?| boolean | true | If true, the expand/collapse state is saved and restored from localStorage. If false, no persistence is used. | | baseClassName? | string | "" | A default CSS class for text segments. | | linkClassName? | string | "" | A CSS class for items with a link property. | | expandableClassName? | string | "" | A CSS class for items that are expandable. Applied to the clickable text before it’s expanded. |

TelescopicItem Type

The component allows for three kinds of items inside the nodes array:

1. String
   Just a basic string to be rendered.
   Example: "Hello"

2. React Node
   Any valid React element.
   Example: <MyCustomComponent />

3. TelescopicTextNodeData object
   This is an object with the following shape:

   interface TelescopicTextNodeData {
     id?: string;
     word?: string | React.ReactNode;
     link?: string;
     linkClassName?: string;
     expandableClassName?: string;
     baseClassName?: string;
     expandTo?: TelescopicItem[];
   }

   • id?
     A unique string identifier used for generating keys. If omitted, the index is used.

   • word?
     The visible text or React node. If it’s expandable, clicking/tapping on this will expand into the expandTo array.

   • link?
     If provided, the word becomes a hyperlink. The link opens in a new tab/window by default.

   • linkClassName?
     CSS class used specifically for this link item. If not provided, falls back to the linkClassName prop on the parent component.

   • expandableClassName?
     CSS class used for the clickable text that’s expandable. If not provided, falls back to the parent’s expandableClassName.

   • baseClassName?
     CSS class for non-expandable text. Overrides the parent’s baseClassName.

   • expandTo?
     An array of items (strings, React nodes, or more objects) to reveal when this word is clicked. This is optional—if omitted, the object is not expandable.

Local Storage / Persistence

By default, TelescopicText will store two arrays in localStorage under the key specified by persistenceKey:

• expanded: The keys of items that have been expanded.
• clicked: The keys of items that have already been clicked.

When a user revisits the page, the component will restore the expanded/clicked state automatically, maintaining the previously expanded text.

If you do not want to persist state, set:

<TelescopicText
  nodes={data}
  enablePersistence={false}
/>

Styling

Because the text is broken up into multiple spans or anchors, you can use the baseClassName, linkClassName, and expandableClassName props to style them appropriately. For example:

/* Example CSS classes */
.base-text {
  color: #333;
}

.link-text {
  color: #3B82F6;
  text-decoration: underline;
  cursor: pointer;
}

.expandable-text {
  color: #C44336;
  font-weight: bold;
  cursor: pointer;
}

Then:

<TelescopicText
  nodes={data}
  baseClassName="base-text"
  linkClassName="link-text"
  expandableClassName="expandable-text"
/>

License

This component is distributed under the MIT License. Feel free to use it in your personal or commercial projects. Contributions and pull requests are welcome!