DOCSEARCHbyAlgolia
Submit Docs

React Chrono

repository·master·Indexed 26 days ago

https://github.com/prabhuignoto/react-chrono

A highly customizable, interactive timeline component for React applications (v3.3.3). It supports multiple layout modes (vertical, horizontal, alternating, and horizontal-all), rich media integration for images and video, and a Grouped API for configuring layout, content, interaction, display, and animations. Features include keyboard navigation, slideshow effects, dark mode, internationalization (i18n), and the ability to create nested timelines.

Tokens
24.6K
Snippets
53
Records
142
Agent score
87%

What's inside react-chrono

  1. Migrate from globalStyle to cardSystem recipes

    master

    To reduce globalStyle usage in horizontal cards, replace old static CSS imports with the cardSystem recipe. This provides type-safe styling for wrappers, headers, and content.

    Target Components:

    • src/components/timeline-elements/timeline-card/timeline-horizontal-card.tsx
    • src/components/timeline-elements/timeline-card/timeline-horizontal-card.styles.ts
    // Replace with cardSystem recipes
import { cardSystem } from '../card-system-v2.css';

// Old globalStyle patterns → New recipes
const wrapper = cardSystem.wrapper({ mode: 'horizontal', interactive: true });
const header = cardSystem.header({ variant: 'default' });
const content = cardSystem.content({ spacing: 'normal' });

  2. Migrate from legacy props to the Grouped API (TimelinePropsV2)

    master

    React Chrono has moved to a grouped API structure (TimelinePropsV2). While legacy props are still supported via automatic migration, you should update your code to use the new grouped objects to avoid development warnings.

    Key Migration Mappings:

    • Layout: Use layout object (e.g., cardWidth → layout.cardWidth, lineWidth → layout.lineWidth).
    • Interaction: Use interaction object (e.g., disableClickOnCircle → interaction.pointClick [inverted]).
    • Content: Use content object (e.g., parseDetailsAsHTML → content.allowHTML).
    • Display: Use display object (e.g., borderLessCards → display.borderless).
    • Media: Use media object (e.g., mediaHeight → media.height).
    • Animation: Use animation object (e.g., slideShow → animation.slideshow.enabled).
    • Style: Use style object (e.g., classNames → style.classNames).
    • Accessibility: Use accessibility object (e.g., buttonTexts → accessibility.buttonTexts).

  4. Internationalize the Timeline (i18n)

    master

    Provide full internationalization support using the i18n prop. This allows you to translate all user-facing text, including navigation, search, theme toggles, and content interactions. Some strings support template variables like {current}, {total}, and {index}.

    // Example: Spanish translation
const spanishTexts = {
  navigation: {
    first: 'Ir al primer elemento',
    last: 'Ir al último elemento',
    next: 'Siguiente elemento',
    previous: 'Elemento anterior',
  },
  search: {
    placeholder: 'Buscar en la Línea de Tiempo',
    clearLabel: 'Limpiar Búsqueda',
  }
};

<Chrono
  items={items}
  i18n={{ texts: spanishTexts, locale: 'es' }}
/>

  5. Migrate from v2 to v3

    master

    React Chrono v3 is backward compatible with v2.x props, but it is recommended to use the new Grouped API for better IDE support and maintainability.

    Prop Mappings

    v2.x Propv3.0 Prop
    borderLessCardsdisplay.borderless
    disableNavOnKeyinteraction.keyboardNavigation (inverted)
    timelinePointDimensionlayout.pointSize
    slideShowanimation.slideshow.enabled
    slideItemDurationanimation.slideshow.duration
    mediaHeightmedia.height
    parseDetailsAsHTMLcontent.allowHTML
    disableToolbardisplay.toolbar.enabled (inverted)

  6. Configure accessibility and ARIA attributes

    master

    React Chrono supports WCAG AA compliance and provides several accessibility features:

    • Keyboard Navigation: Supports Arrow Keys (Left/Right for navigation, Home/End for jumping), Enter (select), Tab (controls), and Escape (exit fullscreen/stop slideshow).
    • ARIA Attributes: Uses role="list", role="listitem", aria-label, aria-current="step", aria-selected, aria-disabled, and aria-hidden="true".
    • Semantic HTML: You can configure semantic tags for titles and subtitles (e.g., h1-h6, span, div) via the content.semanticTags prop.
    • Reduced Motion: Respects the prefers-reduced-motion media query.
    • Custom Labels: Use accessibility.buttonTexts to provide descriptive labels for screen readers.
    <Chrono
  items={items}
  interaction={{ focusOnLoad: true }}
  accessibility={{
    buttonTexts: {
      first: 'Go to Beginning',
      last: 'Go to End',
      next: 'Next Event',
      previous: 'Previous Event'
    }
  }}
  content={{
    semanticTags: {
      title: 'h2',
      subtitle: 'h3'
    }
  }}
/>

  7. Migrate from accessibility to i18n

    master

    The i18n system is the recommended way to handle translations and is fully compatible with the legacy accessibility.buttonTexts configuration. If both are provided, i18n texts take precedence.

    // Legacy (still works)
<Chrono
  accessibility={{
    buttonTexts: { first: 'First' }
  }}
/>

// New i18n (recommended)
<Chrono
  i18n={{
    texts: {
      navigation: { first: 'First' }
    }
  }}
/>

  9. Execute the GlobalStyle reduction migration

    master

    Follow these steps to migrate files from old CSS patterns to the new recipe-based architecture:

    1. Preparation

    • Backup current styles.
    • Create a migration branch: feature/globalstyle-reduction-phase1.
    • Set up visual regression tests.

    2. File-by-File Migration

    1. Analyze Usage: Find all components importing the old CSS file using grep:
      grep -r "timeline-horizontal-card-ve" src/ --include="*.ts" --include="*.tsx"
    2. Update Imports: Switch from old CSS files to the new system (e.g., new-system-v2.css).
    3. Replace Class Usage: Replace static class usage with dynamic recipe calls:
      • Old: <div className={oldStaticClass}>
      • New: <div className={newSystem.component({ variant: dynamicValue })}>
    4. Test & Validate: Perform visual regression, cross-browser, accessibility, and performance testing.
    5. Remove Old File: Delete the old file only after confirming no imports remain.

    3. Verification

    • Run build: npm run build
    • Run tests: npm run test
    • Perform visual inspection and performance comparison.

  10. Install react-chrono

    master

    Install the react-chrono package using your preferred package manager.

    Requirements:

    • React 18.2+ or 19+
    • Node.js 22+
    • TypeScript 4.0+ (optional)
    # Using npm
npm install react-chrono

# Using yarn
yarn add react-chrono

# Using bun (recommended)
bun add react-chrono

  11. Basic Usage of React Chrono

    master

    To use React Chrono, import the Chrono component and provide an array of items. Each item must include a date and can optionally include cardTitle and cardDetailedText.

    import { Chrono } from 'react-chrono';

const items = [
  { date: '2020-01-01', cardTitle: 'Event 1', cardDetailedText: 'Description' },
  { date: '2020-02-01', cardTitle: 'Event 2', cardDetailedText: 'Description' }
];

<Chrono items={items} />