flight-shortcodes

This module enables the use of Shortcodes in any place where you render an HTML string. It is built specifically for Jetshop Flight, but can be used in any React app.

Installing

Use yarn to add it as a dependency to your shop:

$ yarn add @jetshop/flight-shortcodes

Usage

Wherever you want to render something that contains shortcodes, use the Shortcodes component exposed by this package.

import { Shortcodes } from '@jetshop/flight-shortcodes';

const ContentPage = ({ htmlString }) => (
  <Shortcodes
    content={htmlString}
    components={{
      gallery: MyCustomGalleryComponent,
    }}
  />
);

This code will take a string containing HTML and/or shortcodes, turn it into React components and if a shortcode or HTML tag matches a component passed via the components prop, it will use that for rendering.

Example

Adding a shortcode to change text color:

import React from 'react';
import ReactDOM from 'react-dom';
import { Shortcodes } from '@jetshop/flight-shortcodes';

const content = `This text will be [red]of a different color[/red].`;

const Red = ({ children }) => <span style={{ color: '#f00' }}>{children}</span>;

const App = (
  <Shortcodes
    content={content}
    components={{
      Red,
    }}
  />
);

ReactDOM.render(App, document.getElementById('root'));

Note: Shortcodes are case-insensitive due to how the parser works.

You can also pass props to your component using shortcodes:

const content = `This is me: [Image src="profile.jpg" /]`;

// src will get passed to the component as you'd expect:
const Image = ({ src }) => <img src={src} alt="Profile picture" />;

API

The Shortcodes component takes a few props.

content (string)

The original content string containing HTML, shortcodes and/or text.

components ([key: string]: Component)

An object containing shortcode/HTML tag name as key (case-insensitive), and a React component as value. Whenever a shortcode or HTML tag name matches a key provided in this object, it will use that React component to render instead of the native HTML tag.

Any attributes you provide through shortcode or HTML syntax will be passed as props to the React component.

Note: There's a little caveat when using this syntax to pass attributes: [Container visible]Contents[/Container]. In pure React, you would expect this to mean visible={true}, but due to how the HTML spec and the parser used under the hood works, it is parsed to visible="". So be careful if your React component relies on this!

failGracefully (boolean) (default: true)

If this is set to true, we will wrap all components passed in the components prop in an error boundary to gracefully handle errors in the components.

onError (function)

This function will be triggered if an error is thrown in one of the components provided in the components prop, when rendering the shortcodes.

Issues

If you have any problems with this module, please don't hesitate to open an issue in this repository.

Contributions are always appreciated!

Development

To build this module in watch mode run yarn dev.

To build a production release, run yarn build.

To start the test runner, run yarn test.