Getting Started with Custom Components

Simple steps to getting you started with using Custom Components.

If you are looking for the developer documentation for legacy custom components, go to Custom Components (Legacy)

For customers that require advanced customisation, Limio can provide them with a Limio Components Repository. This repository provides a library of open-source Limio Shop Components and a Component Playground to edit these components and build new Custom Components with a set of tools to access Limio Subscription and User data. To gain access to the features outlined in this document please contact Limio Support.

Limio components are React components, so you only need React knowledge to create a custom component in Limio. Additionally, you can use TypeScript in conjunction with React in your custom components.

Anything that you can package up into a React component can be used in Limio. Limio Custom Component frameworks aims to allow developers to do their work in the way most natural to them, this means:

  • To be able to develop locally and see results quickly

  • To be able to support their own release and versioning process

  • To be able to use a CI process to release changes in a controlled environment

  • To own their code

This is a list of requirements & notes on anything that you should/should not do with your component:

  • Your component module must be exported as the default export from your entry file.

  • You can structure your component across many files in multiple directories or just in a single file. (Only .css files are supported for styling.)

  • Use limioProps in your package.json to make your component customisable.

Limio Component Playground

Limio Component Playground is a React Developer Tool that allows developers to import existing Limio Components or newly written Custom Components into an environment that will contain Environment Variables and Limio SDK tools available in Limio Shop at the time of building. This helps to write components that will reliably behave the same in your local environment and once built & published in Limio Subscription Commerce.

Getting Started

Once you have cloned the repository, you will see two directories:

  • component-playground - this contains an interactive playground, with all the context a Limio Shop would have. This allows you to locally develop components as if you were using an instance of the Shop

  • components - this contains all the Components that will be built and made available in Page Builder v2

To get started with making changes navigate to the component-playground directory:

cd component-playground

Then install all the required dependencies, for both your components and the Component Playground, then you are ready to start it up and see your currently active component run:

yarn install
yarn start:dev

This will open your Component on your local machine, which will hot reload every time a change is made to the component.

Inside of your components directory will be a set of open source Limio Components which can be edited to suit the needs of your business. In addition to the existing components, new components can be added here. In conjunction with the Limio SDK these can create a completely bespoke end-user experience.

These components can be imported into the component-playground via the entry file. Located at component-playground/src/App.js

Custom Components

Custom components are bespoke components created to be used in the Limio Shop. It is important to note that whether the components originated from a Limio Component or are made from scratch, they are not supported by future updates to Limio Components and are owned and maintained by your development team.

Each Custom Component can be laid out as you wish, spit into multiple files or a single file containing all of your logic. There are some rules:

  • Custom Component directory must contain a package.json file with relevant dependencies and a limioProps array.

  • Custom Components directory must contain an index.js file which will act as an entry point for the component.

Once the repository has had an update Limio will automatically build all the Components in your repository and make them available in the Component selector under the "Custom Component" category.

The name, description and fields marketers can configure components are set in the component package.json file, inside the name, description and limioProps fields respectively. An example of adding Limio Props to the package.json file of your component. These will get pulled into your component when it is being rendered in Limio and will also be customisable when inside the Page Builder:

{
  "name": "headings",
  "version": "1.0.0",
  "description": "A headings component",
  "main": "./index.js",
  "author": "",
  "dependencies": {
    "@limio/catalog": "^2.1.0",
    "react": "^16.14.0",
    "react-i18next": "^11.3.1"
  },
  "limioProps": [
    {
      "id": "heading",
      "label": "Heading",
      "type": "string",
      "default": "Lorem ipsum dolor sit amet"
    },
    {
      "id": "subheading",
      "label": "Subheading",
      "type": "string",
      "default": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
    }
    {
      "id": "componentId",
      "label": "Component Id",
      "type": "string",
      "default": "headings-limio"
    }
  ]
}

Custom Subcomponents

From Release 102, it is now possible to create custom subcomponents. A subcomponent is one that is intended to be used as part of the Limio Form component. This enables new workflows and means even more customisation is possible when developing a checkout flow. Whether it's inserting custom fields to collect user information or displaying information, it is now possible to deliver that easily with just one small change.

In order to add a custom subcomponent, in your package.json file, simply add the isCustomSubcomponent: true flag.

{
  "name": "headings",
  "version": "1.0.0",
  "description": "A custom subcomponent",
  "main": "./index.js",
  "isCustomSubcomponent": true,
  "author": "",
  "dependencies": {
    ...
  },
  "limioProps": [
    ...
  ]
}

Once your changes have been pushed and the component has been built, you should then be able to see your new custom subcomponent when managing a Form component on a page.

Limio Prop Types

String

{
  "id": "headline",
  "label": "Headline",
  "type": "string",
  "default": "Counting down"
}

Rich Text

Rich text props are saved as a string of html so will need to be rendered using dangerouslySetInnerHTML.

{
  "id": "description__limio_richtext",
  "label": "Description",
  "type": "richtext",
  "default": "<p><strong>Digital</strong></p><p>Description</p><p>No code</p><p>Modern Design</p><p>Server side rendered</p>"
}

Boolean

This prop type will show an on/off toggle.

{
  "id": "hideOnExpire",
  "label": "Hide on expire?",
  "type": "boolean",
  "default": true
}

Color

This prop type will show a colour picker.

{
  "id": "arrowColor__limio_color",
  "label": "Mobile swipe arrow color",
  "type": "color",
  "default": "#4444444"
}

Date Time

This prop type will show a date/time picker.

{
  "id": "expiryDateTime",
  "label": "Expiry Date/Time",
  "type": "datetime",
  "default": "2020-12-10T11:30:42.809Z"
}

List

{
  "id": "buttons",
  "label": "Buttons",
  "type": "list",
  "fields": {
    "buttonText": {
      "id": "buttonText",
      "label": "Button text",
      "type": "string"
    },
    "buttonLocation": {
      "id": "buttonLocation",
      "label": "Button link",
      "type": "string"
    }
  },
  "default": [
    {
      "buttonText": "Learn More",
      "buttonLocation": "https://limio.com"
    }
  ]
}

Picklist

This prop type will show a pick list of all the options with only one being selectable.

{
  "id": "layout",
  "label": "Card layout",
  "type": "picklist",
  "options": [
    {
      "id": "center",
      "label": "Center",
      "value": "center"
    },
    {
      "id": "left",
      "label": "Left",
      "value": "left"
    },
    {
      "id": "right",
      "label": "Right",
      "value": "right"
    }
  ],
  "default": "left"
}

Schema

{
  "id": "consents",
  "label": "Consents",
  "type": "schema",
  "default": [
    {
      "type": "radio",
      "org": "generic",
      "title": "Contact Permissions",
      "for": "email",
      "options": [
        {
          "id": "yes",
          "label": "<p>Yes. I'd like to receive marketing emails.</p>"
        },
        {
          "id": "no",
          "label": "<p>No. I don't want to receive marketing emails.</p>"
        }
      ]
    },
    {
      "type": "checkbox",
      "org": "generic",
      "title": "Terms and Conditions",
      "for": "terms",
      "options": [
        {
          "id": "terms",
          "label": "<p>I agree with the <a href=\"https://www.limio.com?open=terms-and-conditions\" rel=\"noopener noreferrer\" target=\"_blank\">Terms and Conditions</a></p>",
          "required": true,
          "requiredMessage": "Please accept to continue."
        }
      ]
    }
  ]
}

Last updated