@bigcommerce/bigcommerce-react-theme-components
v0.0.1
Published
BigCommerce theme components built for Preact and React
Downloads
6
Maintainers
Keywords
Readme
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.
- Create an API account from your store dashboard.
- Connect your app or theme to the BigCommerce API using your credentials.
- 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.
- Copy this repo into a directory of your choosing within your project.
- in your
package.json
, add an entry underdependencies
for"storefront-ui-components": "link:../YOUR/PATH/TO/THE/REPO"
2.1 For example, since ourexample
app is in the root dir, the link to the package in thatpackage.json
is"link:.."
- run
yarn install
- 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
- 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