Planby

A React based component for a quick implementation of Epg, schedules, live ...

ReactTimelineVirtual list
karolkozer/planbyplanby.netlify.app/planby

README

Planby logo
npm downloads downloads Support us

Description


Planby is a React based component for a quick implementation of Epg, schedules, live streaming, music events, timelines and many more ideas. It uses a custom virtual view which allows you to operate on a really big number of data. The component has a simple API that you can easily integrate with other third party UI libraries. The component theme is customised to the needs of the application design.

Planby preview
Planby preview
Planby preview

Codesandbox example


Live example - Codesandbox

Live example - Typescript Codesandbox

Live example - website with control panel

Testimonials


JW Player logo

We added Planby as the EPG component of the

JWP
open-source
  OTT web app
. The JWP Web App enables developers to quickly build OTT Apps for web platforms, and using Planby developers can easily visualize schedules for 24x7 live streams in their OTT Apps.


Marco van de Veen
Linkedin icon
**Product Manager**
JW Player

🚀 Become a Sponsor! 🚀


Support our activity and help us continue our development -> Open Collective.

Getting Started


Installation


- yarn

  1. ```sh
  2. yarn add planby
  3. ```

- npm

  1. ```sh
  2. npm install planby
  3. ```

Usage


  1. ```tsx
  2. import { useEpg, Epg, Layout } from 'planby';

  4. const channels = React.useMemo(
  5.   () => [
  6.     {
  7.       logo: 'https://via.placeholder.com',
  8.       uuid: '10339a4b-7c48-40ab-abad-f3bcaf95d9fa',
  9.       ...
  10.     },
  11.   ],
  12.   []
  13. );

  15. const epg = React.useMemo(
  16.   () => [
  17.     {
  18.       channelUuid: '30f5ff1c-1346-480a-8047-a999dd908c1e',
  19.       description:
  20.         'Ut anim nisi consequat minim deserunt...',
  21.       id: 'b67ccaa3-3dd2-4121-8256-33dbddc7f0e6',
  22.       image: 'https://via.placeholder.com',
  23.       since: "2022-02-02T23:50:00",
  24.       till: "2022-02-02T00:55:00",
  25.       title: 'Title',
  26.       ...
  27.     },
  28.   ],
  29.   []
  30. );

  32. const {
  33.   getEpgProps,
  34.   getLayoutProps,
  35.   onScrollToNow,
  36.   onScrollLeft,
  37.   onScrollRight,
  38. } = useEpg({
  39.   epg,
  40.   channels,
  41.   startDate: '2022/02/02', // or 2022-02-02T00:00:00
  42. });

  44. return (
  45.   <div>
  46.     <div style={{ height: '600px', width: '1200px' }}>
  47.       <Epg {...getEpgProps()}>
  48.         <Layout
  49.           {...getLayoutProps()}
  50.         />
  51.       </Epg>
  52.     </div>
  53.   </div>
  54. );
  55. ```

or

Custom width and height


  1. ```tsx
  2. const {
  3.   getEpgProps,
  4.   getLayoutProps,
  5.   ...
  6. } = useEpg({
  7.   epg,
  8.   channels,
  9. startDate: '2022/02/02', // or 2022-02-02T00:00:00
  10.   width: 1200,
  11.   height: 600
  12. });

  14. return (
  15.   <div>
  16.      <Epg {...getEpgProps()}>
  17.         <Layout
  18.           {...getLayoutProps()}
  19.         />
  20.       </Epg>
  21.   </div>

  23. ```

or

Time range


  1. ```tsx
  2. const {
  3.   getEpgProps,
  4.   getLayoutProps,
  5.   ...
  6. } = useEpg({
  7.   epg,
  8.   channels,
  9.   startDate: '2022-02-02T10:00:00',
  10.   endDate: '2022-02-02T20:00:00',
  11.   width: 1200,
  12.   height: 600
  13. });

  15. return (
  16.   <div>
  17.      <Epg {...getEpgProps()}>
  18.         <Layout
  19.           {...getLayoutProps()}
  20.         />
  21.       </Epg>
  22.   </div>

  24. ```

API


useEpg


Options


Available options in useEpg

PropertyTypeStatusDescription
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`channels``array`requiredArray
`epg``array`requiredArray
`width``number`optionalEpg
`height``number`optionalEpg
`sidebarWidth``number`optionalWidth
`itemHeight``number`optionalHeight
`dayWidth``number`optionalWidth
`startDate``string`optionalDate
`endtDate``string`optionalDate
`isBaseTimeFormat``boolean`optionalConvert
`isSidebar``boolean`optionalShow/hide
`isTimeline``boolean`optionalShow/hide
`isLine``boolean`optionalShow/hide
`isRTL``boolean`optionalChange
`theme``object`optionalObject
`globalStyles``string`optionalInject

Note about width and height props


Without declaring the width and length properties, the component takes the dimensions of the parent element.

globalStyles


Inject own custom font and other global styles.

  1. ```tsx
  2. const globalStyles = `
  3.   @import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap");

  5.   .planby {
  6.     font-family: "Inter", system-ui, -apple-system,
  7.      "Segoe UI", Roboto, Helvetica, Arial, sans-serif,
  8.      "Apple Color Emoji", "Segoe UI Emoji";
  9.   }

  11.   // Other styles
  12.   ...
  13. `;
  14. ```

Instance Properties


Properties returned from useEpg

PropertyTypeDescription
----------------------------------------------------------------------------
`scrollY``number`Current
`scrollX``number`Current
`onScrollLeft``function(value:Default
`onScrollRight``function(value:Default
`onScrollToNow``function()`Scroll
`onScrollTop``function(value:Default

Channel schema


PropertyTypeStatus
------------------------
`logo``string`required
`uuid``string`required

Epg schema


PropertyTypeStatus
-----------------------------
`channelUuid``string`required
`id``string`required
`image``string`required
`since``string`required
`till``string`required
`title``string`required

Epg


Base props


Available props in Epg

PropertyTypeDescriptionStatus
------------------------------------------------------
`isLoading``boolean`Loaderoptional
`loader``Component`Loaderoptional

Layout


Base props


Available props in Layout.

PropertyTypeDescriptionStatus
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`renderProgram``function({`data`optional
`renderChannel``function({`channel`optional
`renderTimeline``function({sidebarWidth:`sidebarWidth`optional

Render functions


You can use Plaby's style components to develop main features. Moreover, you can integrate with third party UI library eg. Chakra UI, Material UI etc or make custom styles.

renderProgram


Below is an example that allows you to render your custom Program component using Plaby's style components.

  1. ```tsx
  2. import {
  3.   useEpg,
  4.   Epg,
  5.   Layout,
  6.   ProgramBox,
  7.   ProgramContent,
  8.   ProgramFlex,
  9.   ProgramStack,
  10.   ProgramTitle,
  11.   ProgramText,
  12.   ProgramImage,
  13.   useProgram,
  14.   Program,
  15.   ProgramItem
  16. } from "planby";


  19. const Item = ({ program,...rest }: ProgramItem) => {
  20.   const { styles, formatTime, isLive, isMinWidth } = useProgram({ program,...rest });

  22.   const { data } = program;
  23.   const { image, title, since, till } = data;

  25.   const sinceTime = formatTime(since);
  26.   const tillTime = formatTime(till);

  28.   return (
  29.     <ProgramBox width={styles.width} style={styles.position}>
  30.       <ProgramContent
  31.         width={styles.width}
  32.         isLive={isLive}
  33.       >
  34.         <ProgramFlex>
  35.           {isLive && isMinWidth && <ProgramImage src={image} alt="Preview" />}
  36.           <ProgramStack>
  37.             <ProgramTitle>{title}</ProgramTitle>
  38.             <ProgramText>
  39.               {sinceTime} - {tillTime}
  40.             </ProgramText>
  41.           </ProgramStack>
  42.         </ProgramFlex>
  43.       </ProgramContent>
  44.     </ProgramBox>
  45.   );
  46. };

  48. function App() {

  50.   ...

  52. const {
  53.   getEpgProps,
  54.   getLayoutProps,
  55. } = useEpg({
  56.   epg,
  57.   channels,
  58.   startDate: '2022/02/02', // or 2022-02-02T00:00:00
  59. });

  61. return (
  62.   <div>
  63.     <div style={{ height: '600px', width: '1200px' }}>
  64.       <Epg {...getEpgProps()}>
  65.         <Layout
  66.             {...getLayoutProps()}
  67.             renderProgram={({ program,...rest }) => (
  68.               <Item key={program.data.id} program={program} {...rest} />
  69.             )}
  70.           />
  71.       </Epg>
  72.     </div>
  73.   </div>
  74. );
  75. }

  77. export default App;
  78. ```

renderProgram - 12 hours time format


Below is an example that allows you to render your custom Program component with 12 hours time format using Plaby's style components.

  1. ```tsx
  2. ...
  3. const Item = ({ program, ...rest }: ProgramItem) => {
  4.   const {
  5.     styles,
  6.     formatTime,
  7.     set12HoursTimeFormat,
  8.     isLive,
  9.     isMinWidth,
  10.   } = useProgram({
  11.     program,
  12.     ...rest
  13.   });

  15.   const { data } = program;
  16.   const { image, title, since, till } = data;

  18.   const sinceTime = formatTime(since, set12HoursTimeFormat()).toLowerCase();
  19.   const tillTime = formatTime(till, set12HoursTimeFormat()).toLowerCase();

  21.   return (
  22.     <ProgramBox width={styles.width} style={styles.position}>
  23.       <ProgramContent
  24.         width={styles.width}
  25.         isLive={isLive}
  26.       >
  27.         <ProgramFlex>
  28.           {isLive && isMinWidth && <ProgramImage src={image} alt="Preview" />}
  29.           <ProgramStack>
  30.             <ProgramTitle>{title}</ProgramTitle>
  31.             <ProgramText>
  32.               {sinceTime} - {tillTime}
  33.             </ProgramText>
  34.           </ProgramStack>
  35.         </ProgramFlex>
  36.       </ProgramContent>
  37.     </ProgramBox>
  38.   );
  39. };

  41. function App() {

  43.   ...

  45. const {
  46.   getEpgProps,
  47.   getLayoutProps,
  48. } = useEpg({
  49.   epg,
  50.   channels,
  51.   isBaseTimeFormat: true,
  52.   startDate: '2022/02/02', // or 2022-02-02T00:00:00
  53. });

  55. ...
  56. }

  58. export default App;
  59. ```

renderProgram - RTL direction


Below is an example that allows you to render your custom Program component with RTL direction using Plaby's style components.

  1. ```tsx
  2. ...
  3. const Item = ({ program, ...rest }: ProgramItem) => {
  4.   const {
  5.     isRTL,
  6.     isLive,
  7.     isMinWidth,
  8.     formatTime,
  9.     styles,
  10.     set12HoursTimeFormat,
  11.     getRTLSinceTime,
  12.     getRTLTillTime,
  13.   } = useProgram({
  14.     program,
  15.     ...rest
  16.   });

  18.   const { data } = program;
  19.   const { image, title, since, till } = data;

  21.   const sinceTime = formatTime(
  22.     getRTLSinceTime(since),
  23.     set12HoursTimeFormat()
  24.   ).toLowerCase();
  25.   const tillTime = formatTime(
  26.     getRTLTillTime(till),
  27.     set12HoursTimeFormat()
  28.   ).toLowerCase();

  30.   return (
  31.     <ProgramBox width={styles.width} style={styles.position}>
  32.       <ProgramContent width={styles.width} isLive={isLive}>
  33.         <ProgramFlex>
  34.           {isLive && isMinWidth && <ProgramImage src={image} alt="Preview" />}
  35.           <ProgramStack isRTL={isRTL}>
  36.             <ProgramTitle>{title}</ProgramTitle>
  37.             <ProgramText>
  38.               {sinceTime} - {tillTime}
  39.             </ProgramText>
  40.           </ProgramStack>
  41.         </ProgramFlex>
  42.       </ProgramContent>
  43.     </ProgramBox>
  44.   );
  45. };

  47. function App() {

  49.   ...

  51. const {
  52.   getEpgProps,
  53.   getLayoutProps,
  54. } = useEpg({
  55.   epg,
  56.   channels,
  57.   isBaseTimeFormat: true,
  58.   startDate: '2022/02/02', // or 2022-02-02T00:00:00
  59. });

  61. ...
  62. }

  64. export default App;
  65. ```

renderChannel


Below is an example that allows you to render your custom Channel component using Plaby's style components.

  1. ```tsx
  2. import { useEpg, Epg, Layout, ChannelBox, ChannelLogo, Channel } from 'planby';

  4. interface ChannelItemProps {
  5.   channel: Channel;
  6. }

  8. const ChannelItem = ({ channel }: ChannelItemProps) => {
  9.   const { position, logo } = channel;
  10.   return (
  11.     <ChannelBox {...position}>
  12.       <ChannelLogo
  13.         onClick={() => console.log('channel', channel)}
  14.         src={logo}
  15.         alt="Logo"
  16.       />
  17.     </ChannelBox>
  18.   );
  19. };


  22. function App() {

  24.   ...

  26.   const {
  27.     getEpgProps,
  28.     getLayoutProps,
  29.   } = useEpg({
  30.     epg,
  31.     channels,
  32.     startDate: '2022/02/02', // or 2022-02-02T00:00:00
  33.   });

  35.   return (
  36.     <div>
  37.       <div style={{ height: '600px', width: '1200px' }}>
  38.         <Epg {...getEpgProps()}>
  39.           <Layout
  40.               {...getLayoutProps()}
  41.               renderChannel={({ channel }) => (
  42.               <ChannelItem key={channel.uuid} channel={channel} />
  43.             )}
  44.             />
  45.         </Epg>
  46.       </div>
  47.     </div>
  48.   );
  49. }

  51. ```

renderTimeline


Below is an example that allows you to render your custom Timeline component using Plaby's style components.

  1. ```tsx
  2. import {
  3.   TimelineWrapper,
  4.   TimelineBox,
  5.   TimelineTime,
  6.   TimelineDivider,
  7.   TimelineDividers,
  8.   useTimeline,
  9. } from 'planby';

  11. interface TimelineProps {
  12.   isBaseTimeFormat: boolean;
  13.   isSidebar: boolean;
  14.   dayWidth: number;
  15.   hourWidth: number;
  16.   numberOfHoursInDay: number;
  17.   offsetStartHoursRange: number;
  18.   sidebarWidth: number;
  19. }

  21. export function Timeline({
  22.   isBaseTimeFormat,
  23.   isSidebar,
  24.   dayWidth,
  25.   hourWidth,
  26.   numberOfHoursInDay,
  27.   offsetStartHoursRange,
  28.   sidebarWidth,
  29. }: TimelineProps) {
  30.   const { time, dividers, formatTime } = useTimeline(
  31.     numberOfHoursInDay,
  32.     isBaseTimeFormat
  33.   );

  35.   const renderTime = (index: number) => (
  36.     <TimelineBox key={index} width={hourWidth}>
  37.       <TimelineTime>
  38.         {formatTime(index + offsetStartHoursRange).toLowerCase()}
  39.       </TimelineTime>
  40.       <TimelineDividers>{renderDividers()}</TimelineDividers>
  41.     </TimelineBox>
  42.   );

  44.   const renderDividers = () =>
  45.     dividers.map((_, index) => (
  46.       <TimelineDivider key={index} width={hourWidth} />
  47.     ));

  49.   return (
  50.     <TimelineWrapper
  51.       dayWidth={dayWidth}
  52.       sidebarWidth={sidebarWidth}
  53.       isSidebar={isSidebar}
  54.     >
  55.       {time.map((_, index) => renderTime(index))}
  56.     </TimelineWrapper>
  57.   );
  58. }

  60. function App() {

  62.   ...

  64.   const {
  65.     getEpgProps,
  66.     getLayoutProps,
  67.   } = useEpg({
  68.     epg,
  69.     channels,
  70.     startDate: '2022/02/02', // or 2022-02-02T00:00:00
  71.   });

  73.   return (
  74.     <div>
  75.       <div style={{ height: '600px', width: '1200px' }}>
  76.         <Epg {...getEpgProps()}>
  77.           <Layout
  78.               {...getLayoutProps()}
  79.               renderTimeline={(props) => <Timeline {...props} />}
  80.             />
  81.         </Epg>
  82.       </div>
  83.     </div>
  84.   );
  85. }

  87. export default App;
  88. ```

renderTimeline - RTL direction


Below is an example that allows you to render your custom Timeline component using Plaby's style components.

  1. ```tsx
  2. import {
  3.   TimelineWrapper,
  4.   TimelineBox,
  5.   TimelineTime,
  6.   TimelineDivider,
  7.   TimelineDividers,
  8.   useTimeline,
  9. } from 'planby';

  11. interface TimelineProps {
  12.   isRTL: boolean;
  13.   isBaseTimeFormat: boolean;
  14.   isSidebar: boolean;
  15.   dayWidth: number;
  16.   hourWidth: number;
  17.   numberOfHoursInDay: number;
  18.   offsetStartHoursRange: number;
  19.   sidebarWidth: number;
  20. }

  22. export function Timeline({
  23.   isRTL,
  24.   isBaseTimeFormat,
  25.   isSidebar,
  26.   dayWidth,
  27.   hourWidth,
  28.   numberOfHoursInDay,
  29.   offsetStartHoursRange,
  30.   sidebarWidth,
  31. }: TimelineProps) {
  32.   const { time, dividers, formatTime } = useTimeline(
  33.     numberOfHoursInDay,
  34.     isBaseTimeFormat
  35.   );

  37.   const renderTime = (index: number) => (
  38.     <TimelineBox key={index} width={hourWidth}>
  39.       <TimelineTime isBaseTimeFormat={isBaseTimeFormat} isRTL={isRTL}>
  40.         {formatTime(index + offsetStartHoursRange).toLowerCase()}
  41.       </TimelineTime>
  42.       <TimelineDividers>{renderDividers()}</TimelineDividers>
  43.     </TimelineBox>
  44.   );

  46. ...
  47. }

  49. ```

Theme


Schema


Make your theme custom. Below is theme schema that you can pass as one of the options to useEpg hook.

  1. ``` js
  2. const theme = {
  3.   primary: {
  4.     600: '#1a202c',
  5.     900: '#171923',
  6.   },
  7.   grey: { 300: '#d1d1d1' },
  8.   white: '#fff',
  9.   green: {
  10.     300: '#2C7A7B',
  11.   },
  12.   loader: {
  13.     teal: '#5DDADB',
  14.     purple: '#3437A2',
  15.     pink: '#F78EB6',
  16.     bg: '#171923db',
  17.   },
  18.   scrollbar: {
  19.     border: '#ffffff',
  20.     thumb: {
  21.       bg: '#e1e1e1',
  22.     },
  23.   },
  24.   gradient: {
  25.     blue: {
  26.       300: '#002eb3',
  27.       600: '#002360',
  28.       900: '#051937',
  29.     },
  30.   },
  31.   text: {
  32.     grey: {
  33.       300: '#a0aec0',
  34.       500: '#718096',
  35.     },
  36.   },
  37.   timeline: {
  38.     divider: {
  39.       bg: '#718096',
  40.     },
  41.   },
  42. };
  43. ```

All import options


  1. ```tsx
  2. import {
  3.   Epg,
  4.   Layout,
  5.   ChannelBox,
  6.   ChannelLogo,
  7.   ProgramBox,
  8.   ProgramContent,
  9.   ProgramFlex,
  10.   ProgramStack,
  11.   ProgramTitle,
  12.   ProgramText,
  13.   ProgramImage,
  14.   TimelineWrapper,
  15.   TimelineBox,
  16.   TimelineTime,
  17.   TimelineDividers,
  18.   useEpg,
  19.   useProgram,
  20.   useTimeline,
  21.   Program, // Interface
  22.   Channel, // Interface
  23.   ProgramItem, // Interface for program render
  24.   Theme, // Interface
  25. } from 'planby';
  26. ```

License


Distributed under the MIT License. See LICENSE for more information.

Contact


Karol Kozer - @kozerkarol_twitter

Project Link: https://github.com/karolkozer/planby