Skip to content

Latest commit

 

History

History
202 lines (161 loc) · 7.28 KB

README.md

File metadata and controls

202 lines (161 loc) · 7.28 KB
Raw

super-react-gist

Simple and flexible component that allows you to embed GitHub Gists in React projects.

Features

  • Embed a single file from Gist repository!
  • Embed multiple files from multiple Gist repositories!
  • Embed the whole Gist repository!
  • Easy usage: Just copy-paste the Gist's repository URL to embed the whole repository, or copy-paste the permalink of an individual file to include just that.
  • Maximize Development Experience with custom error handling.
  • Lightweight: ~9KB minified (~4kb if gzipped).
  • Packaged as UMD module that can be loaded everywhere.
  • Works both on secret and public repositories.

Table of contents

Installation

Through NPM

To install through npm run:

npm i super-react-gist

As UMD module

super-react-gist comes as UMD module. This means you are able to use super-react-gist component in your browser!

To get started add the following script tag in your html file:

<script src="https://unpkg.com/super-react-gist/umd/super-react-gist.min.js"></script>

Component Properties

Name Type Required Description
url string ✅ The URL of the Gist repository or the permalink of an individual gist file.
file string Optional filename to include.
onLoad function Optional callback triggered on Gist load.
onError function Optional callback triggered on fetch error.
LoadingComponent Component Optional React component to render on Gist loading.
ErrorComponent Component Optional React component to render if Gist fetch fails.

Examples

The following examples illustrate some basic features of the super-react-gist library.

Render one file

With super-react-gist you are able to render a single file from a gist repository.

// Here is a little snippet to get you started!
import React from 'react'
import Gist from 'super-react-gist' // <-- import the library

const MyComponent = () => (
  <div>
    <p>Just enter the file permalink to <em>url</em> prop.</p>
    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' />
  </div>
)

Render multiple files

You are not restricted to use only one Gist component in your project.

import React from 'react'
import Gist from 'super-react-gist' // <-- import the library

const MyComponent = () => (
  <div>
    <p>Rendering multiple files is a piece of cake!</p>
    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' />
    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-multiple-js' />
  </div>
)

Render using file prop

Oh snap! face-palm! In case you didn't notice we can only use the above method to render files that do not contain any uppercase letter. For instance, if our Gist repo contains a file CaMelCase.js, then providing just the permalink will not work!

Q: How can we render this CaMelCase.js file? A: By providing a file prop to our Gist component to indicate which file we want to include.

This is how we do it:

import React from 'react'
import Gist from 'super-react-gist'

const MyComponent = () => (
  <div>
    <p>provide the Gist url without including the file.</p>
    <p>...and pass the filename to `file` prop.</p>
    <Gist
      url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df'
      file='CaMelCase.js'
      />
  </div>
)

Render the whole Gist

Of course, we can also embed the whole Gist repository just by copying the Gist URL.

import React from 'react'
import Gist from 'super-react-gist'

const MyComponent = () => (
  <div>
    <p>provide the Gist URL without include any file.</p>
    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' />
  </div>
)

Use a custom loading component

Most of the times, we would like to render a custom React component while our Gists are loading.

import React from 'react'
import Gist from 'super-react-gist'

const MyComponent = () => (
  <div>
    <p>provide the Gist URL without include any file.</p>
    <Gist 
      url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' 
      LoadingComponent={() => <div>Waiting for Gist...</div>}
    />
  </div>
)

Use a custom error component

In case that fetching fails, we can render a custom React Component to indicate the error.

import React from 'react'
import Gist from 'super-react-gist'

const MyComponent = () => (
  <div>
    <p>provide the Gist URL without include any file.</p>
    <Gist 
      url='https://gist.github.com/GeorgeGkas/NOT_EXIST' 
      ErrorComponent={() => <div>Could not fetch component</div>}
    />
  </div>
)

Listen to error and loading events

Apart from providing a custom error or loading component, we can also register the corresponding callbacks. The onLoad callback is executed when the Gist is fetched successfully, while onError callback is executed if could not retrieve the requested Gist.

import React from 'react'
import Gist from 'super-react-gist'

const MyComponent = () => (
  <div>
    <p>provide the Gist URL without include any file.</p>
    <Gist 
      url='https://gist.github.com/GeorgeGkas/NOT_EXIST' 
      οnLoad={() => console.log('Gist fetched successfully!')}
      onError={() => console.log('Gist could not be fetched!')}
    />
  </div>
)

Combine all the above techniques

This example is left as an exercise to the reader.

Run the examples yourself

Clone the repo git clone https://github.com/georgegkas/super-react-gist.git and then run:

$ npm install
$ npm start

Then you are able to access the Gist component using the Gist global variable. See this Pen for a demonstration.

Bugs and feature requests

Have a bug or a feature request? Please open a new issue.

Contributing

Please read through our contributing guidelines in CONTRIBUTING.md file.

Editor preferences are available in the editor config for easy use in common text editors. Read more and download plugins at http://editorconfig.org.

License

Code released under the MIT License. See LICENSE.md for more details.