@bigcommerce/bigcommerce-react-theme-components

bigcommerce-react-theme-components

BigCommerce theme components built for Preact and React

BigCommerce React Theme Components are a set of core building blocks used to create a UI for your headless BigCommerce app or theme. Use some of the pre-made UI components found in the ui/ directory or build your own using the components in the core/ directory.

See: BigCommerce Developer Docs.

1. Create an API account from your store dashboard.
2. Connect your app or theme to the BigCommerce API using your credentials.
3. Send or retrieve data to/from your store and use it into your React app theme components.

Install

For now, until we deploy a package to NPM, you'll want to use the link feature for npm.

1. Copy this repo into a directory of your choosing within your project.
2. in your package.json, add an entry under dependencies for "storefront-ui-components": "link:../YOUR/PATH/TO/THE/REPO" 2.1 For example, since our example app is in the root dir, the link to the package in that package.json is "link:.."
3. run

yarn install

4. Now you can import components from the library using import { Core, Widget } from 'storefront-ui-components'

Usage

import * as React from 'react'

import { Core, Widget } from 'storefront-ui-components'

class Example extends React.Component {
  render () {
    return (
        <Core.ProductTitle
          tag="h1"
          componentClass="bc-example-product-title"
          componentID="123-title"
          text='Example Product'
          dataAttributes={{['data-title']: 'bc-title-component', ['aria-label']: 'Example Product'}}
        />
    )
  }
}

Components

? Optional props for each Component ** Component accepts children element overrides

Core Components

ProductTitle

Props:

tag?: string default: h2
text: string
classes?: string
tagID?: string
styles?: object
dataAttributes?: object

ProductDescription

Props:

tag?: string default: div
text: string
classes?: string
styles?: object

ProductImage

Props:

src: string
altText?: string
wrapperClasses?: string
classes?: string
styles?: object

ProductPrice

Props:

price: number
salePrice: number
currencySettings: object
tag?: string default: span
classes?: string
tagID?: string
styles?: object
dataAttributes?: object
hasSalePrice?: boolean default: false

ProductBrand

Props:

text: string
tag?: string default: span
classes?: string
styles?: object

ProductCondition

Props:

text: string
tag?: string default: span
classes?: string
styles?: object

ProductCondition

Props:

text: string
tag?: string default: span
classes?: string
styles?: object

ProductInventory

Props:

tag?: string default: span
classes?: string
styles?: object
showInventoryLevel?: boolean
inventoryLevel: number
showWarning?: boolean
inventoryWarningLevel: number
warningMessage?: string

ProductSKU

Props:

text: string
tag?: string default: span
classes?: string
styles?: object

ProductSpecs

Props:

tag?: string default: ul
textObject: object
customFields?: array
classes?: string
styles?: object

ProductReview

Props:

review: ReviewData
tag?: string
classes?: string
tagID?: string
styles?: object
dataAttributes?: object

interface ReviewData {
  date_created: string
  date_modified: string
  date_reviewed: string
  email: string
  id: number
  name: string
  rating: number
  status: string
  text: string
  title: string
}

Utility Components

Notification

Props:

type?: string
message: string
classes?: string
styles?: object

The type options for the notification Components are success (default), info, error, and warning.

Widget/UI Components

ProductCard **

This can be overridden by adding your own JSX children.

Props:

product: object
image: object
brand: object
cardClasses?: string
cardStyles?: object

Default product card utilizes the following core components:

• ProductImage
• ProductTitle
• ProductCondition
• ProductPrice
• Brand

ProductReviews **

This can be overridden by adding your own JSX children.

Props:

reviews: object
tag?: string
classes?: string
tagID?: string
styles?: object
dataAttributes?: object

Default product reviews utilizes the following core components:

• ProductReview

ProductDetailPage **

This can be overridden by adding your own JSX children.

Props:

product: ProductObject
image: ImageObject
brand: BrandObject
reviews?: object
specs?: string[]
currencySettings?: object
PDPClasses?: string
PDPStyles?: object

interface ProductObject {
  name: string
  description: string
  condition: string
  price: number
  sale_price: number
  sku: string
  weight: number
  width: number
  height: number
  depth: number
  reviews_count: number
  reviews_rating_sum: number
}

interface ImageObject {
  url_standard: string
  meta: string
}

interface BrandObject {
  name: string
}

Default product reviews utilizes the following core/UI components:

• ProductImage
• ProductTitle
• ProductCondition
• ProductBrand
• ProductPrice
• StarRating
• ProductSKU
• ProductForm
• Description
• ProductSpecs
• ProductReviews

ProductQuickView **

This can be overridden by adding your own JSX children.

Props:

product: ProductObject
image: ImageObject
brand: BrandObject
currencySettings?: object
PDPClasses?: string
PDPStyles?: object

interface ProductObject {
  name: string
  description: string
  condition: string
  price: number
  sale_price: number
  sku: string
  reviews_count: number
  reviews_rating_sum: number
}

interface ImageObject {
  url_standard: string
  meta: string
}

interface BrandObject {
  name: string
}

Default product reviews utilizes the following core components:

• ProductImage
• ProductTitle
• ProductCondition
• ProductBrand
• ProductPrice
• StarRating
• ProductSKU
• ProductForm
• Description

Cart Components

Provider **

This can be overridden by adding your own JSX children. This component is a provider pattern that will pass cart, style, and event props down to any children passed in.

Props:

cart: CartType
children: any
styles?: object
onUpdate: (method: string, id: string, payload: object) => void
onCheckout?: (value: object) => boolean

Default Cart children are:

• CartItems
• Subtotal
• Checkout

All cart children are provided with props of

• cart
• styles
• onUpdate
• onCheckout

Note that the above styles object is passed to all children, and can style the children components using the following classes:

• cartProvider
• cartItems
• cartItem
• cartItemPrices
• cartItemTotal
• cartSubtotal
• cartSubtotalText
• cartCheckout

CartItems **

Given a cart object with a lineItems object from a bigcommerce cart api call, this object will display the line items with a default Item component that can be overriden. Note that all props can already be provided by CartProvider above.

Props:

cart: CartType
onUpdate: (method: string, id: string, payload: object) => void
styles?: any
ItemComponent?: any

Note: ItemComponent default is the pre-written CartItem shown in examples, and is automatically provided with the same props as CartItems and an additional item prop of type CartItem type

Checkout **

Simply a button that will trigger the onCheckout event provided by the provider when clicked. Default button text will read Checkout, but can be overridden by passing in any children to the component.

Props:

children: object | string
onCheckout: (method: string, id: string, payload: object) => void
styles?: any

Subtotal **

Provided with a cart object from the provider, this component will display the total cart amount based on the cart currency.

Props:

cart: object
styles?: any

Product Form Components

ProductForm

Displays a product form for a passed in product, and provides certain props for children, and events for change and updates.

Props:

product: object
action: string
children: any
onChange?: (value: object) => void
onSubmit?: (value: object) => boolean
method?: string
classes?: string
styles?: object

All children are provided with the following props:

• product
• formData
• onFormChange
• onFormInit

ProductModifiers

Displays product options and modifiers based on modifier and option values from API calls. Also provides sensible defaults for dropdowns, checkboxes, text, and date modifiers.

Props:

modifiers: ModifierConfig[]
map: object
onFormChange?: (value: object) => void
onFormInit?: (value: object) => void

If further modifiers are desired, simply pass in a map prop to modifiers that holds any custom modifiers, using format below, which also show current default modifiers:

const ModifierMap = {
  dropdown: Dropdown,
  checkbox: Checkbox,
  text: Text,
  date: DateInput,
}

Note that the key in the map must relate to the option/modifier type set in BigCommerce API.

All modifier components are provided with modifier data, and an onFormChange event, which propagates all the way up to the above form compnent, if there is one.

Login

LoginForm component

Displays a login form with custom onSubmit, action, and children if necessary.

Props:

onSubmit: (value: object) => boolean
action: string
children: any
styles: any

Default children are Username, Password, RememberMe, LoginButton, and ForgotPassword. All children are provided with styles passed into LoginForm component.

The styles prop is passed to all children and will style the following classes for login:

.loginForm
.username
.usernameLabel
.password
.passwordLabel
.remember
.rememberLabel
.button
.forgotLink

Profile

ProfileForm

ProfileForm component displays certain profile fields from customer profile allowing for edit. Fields can be customized by passing in custom profileKeys prop to handle edit of properties, or by passing in new children, overriding default children generated from profileKeys

Props:

onSubmit: (value: object) => boolean
children: any
customer: CustomerProfile
profileKeys: string[]
styles: any

Current profile keys handle:

• First Name
• Last Name
• Phone
• Email
• Company

The following styles are automatically picked up from the styles prop:

.profileForm
.fieldWrapper
.first_name
.first_name_label
.last_name
.last_name_label
.company
.company_label
.phone
.phone_label
.email
.email_label

ShippingAddresses

Given a list of addresses to display, the ShippingAddresses component iterates over the list, displays them using passed in AddressComponent prop, which defaults to the AddressCard component described below, and provides them with any passed in styles. styles object can contain styles for individual addresses (see below) and addresses for styling container.

Props:

addresses: AddressType[]
AddressComponent: any
styles: any

AddressCard

Displays the address and styles according.

Props:

address: AddressType
styles: any

The following styles are automatically picked up from the styles prop:

.address
.addressName
.address1
.address2
.cityStateZip
.country

ShippingAddressForm

The shipping address form will take a formConfig array to display the shipping address form.

Props

onSubmit: (value: object) => boolean
children?: any
formConfig?: AddressFormField[]
styles?: any
fill?: AddressType

The default formConfig provided is as below:

const defaultFormConfig = [
  {
    name: 'first_name',
    label: 'First Name',
    required: true,
  },
  {
    name: 'last_name',
    label: 'Last Name',
    required: true,
  },
  {
    name: 'company',
    label: 'Company',
  },
  {
    name: 'address1',
    label: 'Address Line 1',
    required: true,
  },
  {
    name: 'address2',
    label: 'Address Line 2',
  },
  {
    name: 'city',
    label: 'City',
    required: true,
  },
  {
    name: 'postal_code',
    label: 'Postal Code',
    required: true,
  },
  {
    name: 'state_or_province',
    label: 'State',
    required: true,
    component: StateSelect,
  },
  {
    name: 'country_code',
    label: 'State',
    required: true,
    component: CountrySelect,
  },
  {
    name: 'phone',
    label: 'Phone',
  },
]

Note that custom components can be specified for any formConfig field. Custom components will be provided with styles, an onFieldChange event, the field config, and the current address object. The default component for fields is simply an input component.

Field styles that are pulled from the styles object are provided for the wrapper, label, and the actual input component. For example, for the first_name field, the following classes will be accepted and passed down:

.first_name
.first_name-wrapper
.first_name-label

In addition to the above styles, the following styles are also provided:

.addressForm
.fieldWrapper
.saveButton

CountrySelect

Displays select element with list of countries, uses the country-state-city npm package.

Props

onChange: (value: object) => void
name: string
value?: string
className?: string
id: string

StateSelect

Displays select element with list of selects when given a country code in the address object, uses the country-state-city npm package.

Props

onChange: (value: object) => void
name: string
value?: string
className?: string
id: string
address?: AddressType

Wishlists

WishlistList

Given a list of wishlists to display, the WishlistList component iterates over the list, displays them using passed in WishlistComponent prop, which defaults to the WishlistRow component described below, and provides them with any passed in styles. The onWishlistAction prop gets passed to each WishlistComponent, and will get passed with action and wishlist parameters

Props:

wishlists: Wishlist[]
WishlistComponent?: any
styles: any
onWishlistAction: (action: string, wishlist: Wishlist) => void

The following styles are automatically provided to the styles prop:

.wishlists
.wishlist
.wishlistInfo
.wishlistName
.wishlistItems
.wishlistShared
.wishlistActions

WishlistRow

Given a wishlist object, this default component will display the wishlist name, pass in styles down to the component, and pass through any actions to the onWishlistAction prop. The current expectation is that code outside of the component will handle the actions below:

click - triggered when wishlist name is clicked
share - triggered when share button is clicked
edit - triggered when edit button is clicked
delete - triggered when delete button is clicked

Note that onWishlistAction will be called with both an action and the wishlist object passed into WishlistRow

Props:

wishlist: Wishlist
styles: any
onWishlistAction: (action: string, wishlist: Wishlist) => void

The following styles are automatically provided to the styles prop:

.wishlist
.wishlistInfo
.wishlistName
.wishlistItems
.wishlistShared
.wishlistActions
.shareWishlistButton
.editWishlistButton
.deleteWishlistButton

WishlistDetail

The WishlistDetail component will display the wishlist passed in, along with the products in the wishlist. Due to api reponses, when passing in the wishlist, a list of products must be provided that match the wishlist items array. Each product in the wishlist will be displayed using the productComponent prop, which defaults to the WishlistProductRow component described below.

Props:

wishlist: Wishlist
products: WishlistProduct[]
onWishlistAction?: (action: string, wishlist: Wishlist) => void
currencySettings: object
productComponent?: React.Component
styles: any

The following styles are automatically provided to the styles prop:

.wishlistDetail
.wishlistDetailName

WishlistProductRow

The WishlistProductRow displays a product from a wishlist when given the product, passes in styles, and handles removal of products using the onWishlistAction pattern described above. When the product remove button is clicked, the provided onWishlistAction prop will be called with the remove_product action, and the new wishlist object without the product.

Props:

wishlist: Wishlist
product: WishlistProduct
currencySettings: object
onWishlistAction: (action: string, wishlist: Wishlist) => void
styles: any

The following styles are automatically provided to the styles prop:

styles.wishlistProduct
styles.wishlistProductLink
styles.wishlistPrice
styles.wishlistProductRemove

Storybook

There currently aren't many storybooks, but they are being added as we work on the library. To run the storybook, simply run: yarn storybook and a browser window will open.

License

MIT © BigCommerce