@colabcommerce/elementsReact

Elements — React component library

Drop-in React components, providers, and hooks for store locators, store detail pages, quote flows, and lead capture. Every component is a build entry and is published as a separate subpath export so you only ship what you use.

Install Entry index

On this page

Introduction

@colabcommerce/elements is the React building-block library that powers the Colab Commerce storefront experiences. It exposes UI primitives, three feature groups (store locator, store detail, quote flow), supporting hooks, and an i18n provider — all as individually importable subpath exports.

Many components are context-driven and only work when rendered under the matching provider. Each entry below documents its context requirement.

Install

The package is published to the Colab Commerce private registry. Configure your .npmrc with an access token, then add the package:

npm install @colabcommerce/elements

Import only the entries you need (each is a separate subpath export) and pull in the styles entry once at your app root:

app.jsx

import '@colabcommerce/elements/styles'
import StoreLocator from '@colabcommerce/elements/StoreLocator'

export default function App() {
  return (
    <StoreLocator
      organizationId={process.env.NEXT_PUBLIC_CC_ORG_ID}
      locale="en"
    />
  )
}

How entries work

Each file in src/entries becomes a build entry and a distributable module in dist.
Package subpath exports are defined in package.json — import any entry directly by name (e.g. @colabcommerce/elements/StoreLocator).
Many feature components are context-driven and only work when rendered under the correct provider.

Context legend

None — component or hook can be used directly.
StoreProvider — must be inside a StoreProvider tree.
StoreLocatorProvider — must be inside a StoreLocatorProvider tree.
QuoteFormProvider — must be inside a QuoteFormProvider tree.
TranslationsProvider — requires i18n context for translation keys.
APIProvider — requires the @vis.gl/react-google-maps APIProvider for map primitives.
Self-wrapped — the component renders all required providers internally, so no caller-side context is required.

Entry index

Every importable subpath at a glance. See the detailed reference for props, exports, and notes per entry.

Entry	Exports	Context
`Badge`	default + named	None
`Button`	default + named	None
`Card`	default + named	None
`CollapsibleStoreHours`	default	TranslationsProvider
`HoursList`	default	TranslationsProvider
`Input`	default	None
`LeadForm`	default	TranslationsProvider
`LoadingPuff`	default	None
`MessageDialog`	default	None
`Panel`	default	None
`PhoneNumberInput`	default + named	None
`QuoteForm`	default	Self-wrapped
`QuoteFormButton`	default	Self-wrapped
`QuoteFormProvider`	default + named	None
`QuoteFormSearch`	default	QuoteFormProvider
`QuoteFormStoreList`	default	QuoteFormProvider
`QuoteFormStoreListItem`	default	TranslationsProvider
`QuoteLeadForm`	default	QuoteFormProvider
`QuoteMap`	default	QuoteFormProvider + APIProvider
`QuoteMapMarker`	default	APIProvider
`StaticMap`	default	None
`Store`	default	Self-wrapped
`StoreContact`	default	StoreProvider + TranslationsProvider
`StoreInfo`	default	StoreProvider + TranslationsProvider
`StoreList`	default	StoreLocatorProvider
`StoreListItem`	default	TranslationsProvider
`StoreListNoneFound`	default	None
`StoreLocator`	default	Self-wrapped
`StoreLocatorMap`	default	StoreLocatorProvider + APIProvider
`StoreLocatorMapMarker`	default	APIProvider
`StoreLocatorMessageDialog`	default	StoreLocatorProvider
`StoreLocatorProvider`	default + named	None
`StoreLocatorSearch`	default	StoreLocatorProvider
`StoreMap`	default	StoreProvider
`StoreMeta`	default	None
`StoreProducts`	default	StoreProvider + TranslationsProvider
`StoreProvider`	default + named	None
`TranslationsProvider`	default + named alias	None
`styles`	side-effect	None
`useGeolocation`	default	None
`useQuoteForm`	default + named	QuoteFormProvider
`useStore`	default + named	StoreProvider
`useStoreLocator`	default + named	StoreLocatorProvider

UI primitives

Headless, variant-based building blocks shared by the feature components. Safe to use anywhere — no context required.

Badge

Variant-based badge primitive.

Exports

default: Badge · named: Badge, badgeVariants

Context

None

Props

className
variant — default | secondary | destructive | outline | success
asChild — boolean — default false
…elementProps

Button

Button primitive with variants and sizes.

Exports

default: Button · named: Button, buttonVariants

Context

None

Props

className
variant — default | destructive | outline | secondary | ghost | link
size — default | sm | lg | icon | icon-sm | icon-lg
asChild — boolean — default false
…buttonProps

Card

Composable card primitive set.

Exports

default: Card · named: Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent

Context

None

Props

className — accepted by every Card primitive plus standard element props

Input

Styled text input primitive.

Exports

default

Context

None

Props

className
type
…inputProps

LoadingPuff

SVG loading indicator.

Exports

default

Context

None

Props

size — number — default 48

Panel

Animated panel primitive with open or closed state.

Exports

default

Context

None

Props

active — boolean
children
className

PhoneNumberInput

Controlled phone input wrapper over Input.

Exports

default: PhoneNumberInput · named: PhoneNumberInput

Context

None

Props

value
onChange
onBlur
…inputProps — ref is forwarded

Store locator

Components and provider for an embeddable store locator with map, search, and results list. The StoreLocator shell wires every dependency internally; the lower-level pieces let you assemble a custom layout under your own StoreLocatorProvider.

StoreLocator

Full locator shell with map, search, and list.

Exports

default

Context

Self-wrapped (StoreLocatorProvider + TranslationsProvider + APIProvider)

Props

organizationId
locale
showProducts — boolean — default false
productLimit — number — default 10
baseUrl — string — default /retailers

StoreLocatorProvider

Context provider for store locator state.

Exports

default: StoreLocatorProvider · named: StoreLocatorProvider

Context

None

Props

organizationId
locale
baseUrl — string — default /retailers
children

Notes

Provides selected / focused store state, the message dialog state, search location and radius, the active stores + metadata from the search hooks, and the locator config / loading / error state.

StoreLocatorSearch

Autocomplete and radius search controls.

Exports: default
Context: StoreLocatorProvider

StoreLocatorMap

Interactive locator map.

Exports: default
Context: StoreLocatorProvider + APIProvider

StoreLocatorMapMarker

Marker and info window for the locator map.

Exports

default

Context

APIProvider

Props

store
isSelected
onClick

StoreLocatorMessageDialog

Bridges the locator context into MessageDialog.

Exports: default
Context: StoreLocatorProvider

StoreList

Locator search results list.

Exports: default
Context: StoreLocatorProvider

StoreListItem

Single locator result row with actions.

Exports

default

Context

TranslationsProvider

Props

id
name
placeId
addressLineOne
addressLineTwo
city
province
postalCode
country
phone
hours
distance
services — array — default []
products — array — default []
showProducts — boolean — default false
productLimit — number — default 10
isSelected
handleSelect
onMessageClick
href

StoreListNoneFound

Empty-result state component.

Exports: default
Context: None

Store

Components and provider for single-store detail pages (header, hours, contact, product grid, map).

Store

Full store details page shell.

Exports

default

Context

Self-wrapped (StoreProvider + TranslationsProvider)

Props

id
organizationId
locale
baseUrl — string — default /retailers
initialData

StoreProvider

Context provider for single-store details.

Exports

default: StoreProvider · named: StoreProvider

Context

None

Props

organizationId
id
locale
baseUrl — string — default /retailers
initialData
children

Notes

Provides organizationId, id, locale, baseUrl, store.

StoreInfo

Store header, status, and summary block.

Exports: default
Context: StoreProvider + TranslationsProvider

StoreContact

Contact details and hours block.

Exports: default
Context: StoreProvider + TranslationsProvider

StoreProducts

Product grid and filtering panel for a store.

Exports: default
Context: StoreProvider + TranslationsProvider

StoreMap

Store map section.

Exports: default
Context: StoreProvider

StoreMeta

Placeholder metadata component.

Exports: default
Context: None
Notes: Currently placeholder output.

Quote form

End-to-end quote request flow: pick a product, find a fulfilling retailer location, submit a lead. The QuoteForm and QuoteFormButton entries wrap every required provider internally; the lower-level pieces let you compose a custom flow under your own QuoteFormProvider.

QuoteForm

Main quote flow component.

Exports

default

Context

Self-wrapped (QuoteFormProvider + TranslationsProvider + APIProvider)

Props

organizationId
products
locale
onClose
onSuccess

QuoteFormButton

Button trigger that opens the QuoteForm dialog.

Exports

default

Context

Self-wrapped

Props

organizationId
products
productKey
locale
onClose
onSuccess

QuoteFormProvider

Context provider for quote-flow state and search data.

Exports

default: QuoteFormProvider · named: QuoteFormProvider

Context

None

Props

organizationId
locale
baseUrl — string — default /retailers
products — array — default []
productKey
filterBy — object — default { stocked: [sku], available: [sku] }
children

Notes

Provides the step index, selected and focused store ids, message state, search settings and location, the stores + metadata from search hooks, and the locator config / loading / error state.

QuoteFormSearch

Autocomplete search input for the quote flow.

Exports: default
Context: QuoteFormProvider

QuoteFormStoreList

Filtered quote store list tied to requested products.

Exports: default
Context: QuoteFormProvider

QuoteFormStoreListItem

Store list row for the quote flow with availability signaling.

Exports

default

Context

TranslationsProvider

Props

id
name
placeId
addressLineOne
addressLineTwo
city
province
postalCode
country
phone
hours
distance
services — array — default []
isFocused
handleFocus
handleSelect
requestedProducts
locationProducts
filterBy

QuoteLeadForm

Quote-specific lead form wrapper that reads quote context.

Exports

default

Context

QuoteFormProvider

Props

onClose
onSuccess

QuoteMap

Map panel for quote-flow store selection.

Exports: default
Context: QuoteFormProvider + APIProvider

QuoteMapMarker

Marker and info window for the quote map.

Exports

default

Context

APIProvider

Props

store
isSelected
onClick
onSelect

Hours

CollapsibleStoreHours

Collapsible hours block with open/closed and opening/closing-soon messaging.

Exports

default

Context

TranslationsProvider

Props

hours — array of store hour records
openingSoonMinutes — number — default 60
closingSoonMinutes — number — default 60
className — string — default ""

HoursList

Flat list of weekly store hours.

Exports

default

Context

TranslationsProvider

Props

hours — array of store hour records
openingSoonMinutes — number — default 60
closingSoonMinutes — number — default 60
className — string — default ""

Lead capture

LeadForm

Lead-capture form that posts to the widget API.

Exports

default

Context

TranslationsProvider

Props

organizationId
selectedLocationId
storeName
location
activityType
products
isOpen
onClose
onSuccess

Notes

Uses validation and phone parsing. Sends payload to the widget lead endpoint.

MessageDialog

Contact / message modal for a store.

Exports

default

Context

None

Props

organizationId
storeName
isOpen
onClose
onSuccess

Maps

StaticMap

Static map image renderer.

Exports

default

Context

None

Props

center
zoom
size — string — default "400x600"
markers

Hooks

Stand-alone React hooks. Some require a matching provider in the tree — see each entry for its context requirement.

useGeolocation

Geolocation hook with browser and IP fallback.

Exports: default
Context: None
Notes: Signature: useGeolocation(autoGeoLocate = true, geoOptions = {}, ipOptions = {}). Returns location, source, isLoading, error, refresh, Locate, clearLocationCache, isGeolocationAvailable, and isGeolocationEnabled.

useQuoteForm

Accessor hook for the QuoteFormProvider context.

Exports: default: useQuoteForm · named: useQuoteForm
Context: QuoteFormProvider
Notes: Signature: useQuoteForm(). Returns the quote form context object.

useStore

Accessor hook for the StoreProvider context.

Exports: default: useStore · named: useStore
Context: StoreProvider
Notes: Signature: useStore(). Returns the store context object. Throws when used outside a StoreProvider.

useStoreLocator

Accessor hook for the StoreLocatorProvider context.

Exports: default: useStoreLocator · named: useStoreLocator
Context: StoreLocatorProvider
Notes: Signature: useStoreLocator(). Returns the store locator context object.

Translations & styles

TranslationsProvider

i18next provider wrapper for the library components.

Exports

default: LibraryI18nProvider · named alias: TranslationsProvider

Context

None

Props

children
options — object — default {}

styles

Side-effect entry that includes src/dist.css.

Exports: default empty object
Context: None
Notes: Import once at your app root: import '@colabcommerce/elements/styles'.

Caveats

Some map and geolocation paths rely on Google Maps APIs and require APIProvider or a valid API key depending on the component.
Some entries are intentionally thin wrappers and inherit behaviour from their source modules.
StoreMeta is currently a placeholder implementation.
Some hooks warn when used outside their provider; others — notably useStore — throw.

Source: @colabcommerce/elements · entries in src/entries.