How does it work

Rally Elements are customizable UI elements that can be used to build a complete checkout flow. Rally elements are web components which makes them framework agnostic. The elements have a default configuration, allowing you to add them directly to the DOM. Additionally, you can configure and customize these elements according to your needs.

Brief Intro to Web Components

Web components are a lot like components that are used in frameworks with the exception that they are framework agnostic meaning that they can be used anywhere on the green web, but also follow the HTML element interface.

Get started

You can install and set up Rally elements using either the NPM package or by including the script on the client side.

NPM Package

Install the package using npm:

npm install @rallycommerce/elements

Import the package and initialize:

import { Rally } from '@rallycommerce/elements';
Rally.init('clientId');

Client-side Script

Include the script and initialize:

<script src="https://js.onrally.com/elements/elements.js"></script>
<script>
  Rally.init('clientId');
</script>

Initialization and Session Configuration

During initialization, you can configure Rally by passing an optional configuration object as a second parameter to `Rally.init()`. This object enables you to set up various options, such as custom checkout flows, session origins, and line items.

const config = {
  customCheckoutFlow: { disableRedirect: true },
  sessionOrigin: 'landing_page',
  lineItems: [
    {
      productId: 300,
      quantity: 1,
      includeDetails: true,
    },
  ],
};

Rally.init('clientId', config);

Incorporating Elements into HTML

To include Rally elements in your HTML file, simply add them. For example, to insert an email element, use the `rally-email` tag in your HTML file.

<rally-email></rally-email>

Configure Elements

To configure Rally elements, you can use one of the following methods:

Data Attribute

Pass the configuration as a JSON-formatted string using the `config` data attribute:

<rally-email config='{"field": {"label": "New email label"}}'></rally-email>

SDK

Configure elements with the SDK:

const newEmailConfig = {...};
Rally.elements.configure('email_id', newEmailConfig);

// Alternatively, use an HTMLElement instead of the ID:
const emailElement = document.querySelector('rally-email');
Rally.elements.configure(emailElement, newEmailConfig);