{"id":20164972,"url":"https://github.com/openscript-ch/react-alternating-timeline","last_synced_at":"2025-04-10T00:51:54.491Z","repository":{"id":65762519,"uuid":"586938127","full_name":"openscript-ch/react-alternating-timeline","owner":"openscript-ch","description":"A compact, masonry style alternating timeline react component which is fully customizable.","archived":false,"fork":false,"pushed_at":"2025-04-08T12:03:43.000Z","size":6909,"stargazers_count":1,"open_issues_count":15,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T00:51:48.493Z","etag":null,"topics":["component","react","react-component"],"latest_commit_sha":null,"homepage":"https://openscript-ch.github.io/react-alternating-timeline/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openscript-ch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-09T15:30:24.000Z","updated_at":"2024-05-09T13:33:50.000Z","dependencies_parsed_at":"2023-09-27T12:36:45.805Z","dependency_job_id":"3a877f8a-7e51-4a62-a77e-af0e33ba1cd2","html_url":"https://github.com/openscript-ch/react-alternating-timeline","commit_stats":{"total_commits":418,"total_committers":6,"mean_commits":69.66666666666667,"dds":0.2559808612440191,"last_synced_commit":"187dfc24a5ea36760c1ea9aa9bdc88de24e3ea49"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":"openscript-ch/react-vite-storybook-typescript-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openscript-ch%2Freact-alternating-timeline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openscript-ch%2Freact-alternating-timeline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openscript-ch%2Freact-alternating-timeline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openscript-ch%2Freact-alternating-timeline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openscript-ch","download_url":"https://codeload.github.com/openscript-ch/react-alternating-timeline/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137997,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","react","react-component"],"created_at":"2024-11-14T00:36:14.020Z","updated_at":"2025-04-10T00:51:54.462Z","avatar_url":"https://github.com/openscript-ch.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-alternating-timeline\n\nA simple and compact, true masonry style alternating timeline react component which is fully customizable and free stylable.\n\n![Demonstration](./docs/demonstration.jpg)\n\n## Features\n\n- 🎛️ Customize everything.\n- 🎨 Consistent ([BEM](https://getbem.com)) class naming for easy styling with CSS, emotion...\n- ⏰ Custom date formatting.\n- ⚖️ Alternating, left or right positioning.\n- 🖼️ Render images and custom content.\n- 🪄 Built with Typescript.\n\n## Installation\n\nAdd the package with the package manager via NPMs or GitHubs registry of choice to your project:\n\n- **yarn**: `yarn add react-alternating-timeline`\n- **npm**: `npm install react-alternating-timeline`\n- **pnpm**: `pnpm add react-alternating-timeline`\n- **npx**: `npx -p react-alternating-timeline`\n\n## Usage\n\n```ts\nimport { Timeline, TimelineItemsProps } from 'react-alternating-timeline';\n\nconst items: TimelineItemsProps = [\n  {\n    key: 'first',\n    date: new Date(),\n    title: 'Special event!',\n  },\n  {\n    key: 'second',\n    date: new Date(),\n    title: 'Event',\n    children: \u003cimg src=\"./test.jpg\" alt=\"test\" /\u003e,\n  },\n  ...\n];\n\n\u003cTimeline items={items} /\u003e;\n```\n\n## API\n\nThe available properties of the `Timeline` component:\n\n| Property         | Type                                        | Description                                                                   | Default         |\n| :--------------- | :------------------------------------------ | :---------------------------------------------------------------------------- | :-------------- |\n| `items`          | [`TimelineItemsProps`](#timelineitemsprops) | Array of timeline items                                                       |                 |\n| `positioning?`   | `'alternating' \\| 'left' \\| 'right'`        | How the items should be positioned relative to the timeline                   | `'alternating'` |\n| `minMarkerGap?`  | `number`                                    | The minimum gap markers will have between each other                          | 50 (`px`)       |\n| `formatDate?`    | `(date: Date) =\u003e string`                    | Callback to format date                                                       |                 |\n| `customMarker?`  | `ReactElement`                              | Custom maker element replacing the default                                    |                 |\n| `customPointer?` | `ReactElement`                              | Custom pointer element replacing the default                                  |                 |\n| `styleConfig?`   | [`StyleConfig`](#styling)                   | Style config object for customizing timeline by setting css custom properties |                 |\n| `className?`     | `string`                                    | Additional class name                                                         |                 |\n\n### TimelineItemsProps\n\nAn array of the following properties:\n\n| Property         | Type                     | Description                                                                      |\n| :--------------- | :----------------------- | :------------------------------------------------------------------------------- |\n| `key`            | `Key`                    | Unique key for each item                                                         |\n| `title?`         | `string`                 | Optional title paragraph displayed bold                                          |\n| `date`           | `Date \\| string`         | Date either being formatted according to provided format or passed as a `string` |\n| `children?`      | `ReactNode`              | Pass custom content as `children` to the component                               |\n| `formatDate?`    | `(date: Date) =\u003e string` | Callback to format date of specific item                                         |\n| `customMarker?`  | `ReactElement`           | Overwriting `customMarker` property of parent `Timeline`                         |\n| `customPointer?` | `ReactElement`           | Overwriting `customPointer` property of parent `Timeline`                        |\n\n## Styling\n\nThe style can either be passed as an object through the `styleConfig` property...\n\n```ts\n{\n  line?: {\n    width?: CSSProperties['width'];\n    color?: CSSProperties['backgroundColor'];\n    overhang?: CSSProperties['paddingBlock'];\n  };\n  item?: {\n    gap?: CSSProperties['gap'];\n    startOffset?: {\n      left?: CSSProperties['marginTop'];\n      right?: CSSProperties['marginTop'];\n    };\n  };\n  marker?: {\n    size?: CSSProperties['width'];\n    color?: CSSProperties['backgroundColor'];\n    radius?: CSSProperties['borderRadius'];\n  };\n  pointer?: {\n    height?: CSSProperties['height'];\n    width?: CSSProperties['width'];\n    minOffset?: CSSProperties['marginTop'];\n  };\n  card?: {\n    background?: CSSProperties['backgroundColor'];\n    radius?: CSSProperties['borderRadius'];\n    shadow?: CSSProperties['boxShadow'];\n    padding?: CSSProperties['padding'];\n    offset?: CSSProperties['gap'];\n  };\n}\n```\n\n...or can be set as custom properties directly in css\n\n```css\n.timeline {\n  --line-width: 0.2rem;\n  --line-color: black;\n  --line-overhang: 1rem;\n  --item-gap: 1rem;\n  --item-start-offset-left: 0;\n  --item-start-offset-right: 5rem;\n  --marker-size: 1rem;\n  --marker-color: var(--line-color);\n  --marker-radius: 50%;\n  --pointer-height: 2rem;\n  --pointer-width: 1rem;\n  --pointer-min-offset: 5rem;\n  --card-background: whitesmoke;\n  --card-radius: 0.1rem;\n  --card-shadow: unset;\n  --card-padding: 1rem;\n  --card-offset: 1rem;\n}\n```\n\n### StyleConfig\n\n| Name                       | Description                                                                                                    | Default       |\n| :------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------ |\n| **Line**                   | The line the timeline items are place around/beside                                                            |               |\n| – `line-width`             | Width of the line                                                                                              | `0.2rem`      |\n| – `line-color`             | Color of the line                                                                                              | `black`       |\n| – `line-overhang`          | How much the line should overhang the beginning and end of the timeline component                              | `1rem`        |\n| **Item**                   | The timeline item as a whole, including the card, pointer and marker                                           |               |\n| – `item-gap`               | The vertical space between the items                                                                           | `1rem`        |\n| – `item-start-offset-left` | How much the items on the left side should be offset from the top                                              | `0`           |\n| – `item-start-offset-left` | How much the items on the right side should be offset from the top                                             | `5rem`        |\n| **Marker**                 | The markers on the line which marks the chronological order of the timeline items                              | `1rem`        |\n| – `marker-size`            | Size of the default marker                                                                                     | `1rem`        |\n| – `marker-color`           | Color of the default marker                                                                                    | `line-color`  |\n| – `marker-radius`          | Border radius (roundness) of the marker edges                                                                  | `50%` (round) |\n| **Pointer**                | The pointers pointing from the item cards to the markers on the line                                           |               |\n| – `pointer-height`         | Height of the default pointer                                                                                  | `2rem`        |\n| – `pointer-width`          | Width of the default pointer                                                                                   | `1rem`        |\n| – `pointer-min-offset`     | Minimum offset of the pointer to the top of the card. The actual offset depends on the `minMarkerGap` property | `5rem`        |\n| **Card**                   | The cards in which the timeline item content is displayed                                                      |               |\n| – `card-background`        | Background color of the card                                                                                   | `whitesmoke`  |\n| – `card-radius`            | Border radius of the card edges                                                                                | `0.1rem`      |\n| – `card-shadow`            | Configure drop shadow of the card                                                                              | `unset`       |\n| – `card-padding`           | Padding of the card content                                                                                    | `1rem`        |\n| – `card-offset`            | Space between the card and the timeline line                                                                   | `1rem`        |\n\n## Demo\n\nView a full demo of component as storybook: [Storybook](https://openscript-ch.github.io/react-alternating-timeline/) 📚\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenscript-ch%2Freact-alternating-timeline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenscript-ch%2Freact-alternating-timeline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenscript-ch%2Freact-alternating-timeline/lists"}