Customization

Qariyb widgets use a three-layer theming system inspired by Stripe's Appearance API. Start with a preset, override specific variables, then fine-tune with CSS rules.

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  theme: 'dark',           // Layer 1: Preset
  variables: {             // Layer 2: Overrides
    colorPrimary: '#8b5cf6',
    borderRadius: '12px',
  },
  rules: {                 // Layer 3: CSS rules
    '.Button--primary': {
      textTransform: 'uppercase',
    },
  },
};

Theme Presets

Theme presets are complete sets of design tokens optimized for different use cases.

Available Presets

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  theme: 'light', // 'light' | 'dark' | 'flat' | 'minimal'
};

Or per-component:

<qariyb-checkout event-id="01HW..." theme="dark"></qariyb-checkout>

light (Default)

Clean, professional appearance with white backgrounds and emerald accent.

Token	Value	Description
`primary`	`#10b981`	Emerald green (Qariyb brand)
`background`	`#ffffff`	Pure white
`text`	`#1f2937`	Dark gray
`border`	`#e5e7eb`	Light border

Best for: Most websites, professional/business events, clean designs.

dark

Dark mode theme with slate grays and light text.

Token	Value	Description
`primary`	`#34d399`	Emerald green, lightened for contrast on dark
`background`	`#1f2937`	Dark slate
`text`	`#f9fafb`	Near white
`border`	`#4b5563`	Medium gray

Best for: Dark mode websites, entertainment/nightlife events, media-heavy sites.

flat

Minimalist theme with no shadows and simpler visual hierarchy.

Token	Value
`shadows.sm`	`none`
`shadows.base`	`none`
`shadows.md`	`none`
`shadows.lg`	`none`
`shadows.xl`	`none`

Best for: Minimalist designs, content-heavy pages, print-style layouts.

minimal

Ultra-clean theme with reduced visual weight and tighter spacing.

Token	Value	Difference
`radii.base`	`4px`	Smaller (vs 8px)
`primary`	`#374151`	Neutral slate instead of emerald
`text`	`#171717`	Near black
`border`	`#e5e5e5`	Lighter
`shadows.base`	`none`	No shadows

Best for: Embedding in existing UIs, when widgets should blend in.

Resolution Order

Components resolve their theme in this order:

Component theme attribute (if set)
Global QariybConfig.theme (if set)
Default: 'light'

Theme Variables

Variables override specific design tokens while inheriting the rest from your chosen preset.

Color Variables

Primary Colors

Name
colorPrimary
Type
string
Description
Main accent color for buttons, links, and focus states.
Name
colorPrimaryText
Type
string
Description
Text color on primary backgrounds.

variables: {
  colorPrimary: '#4f46e5',      // Indigo
  colorPrimaryText: '#ffffff',  // White text on buttons
}

Background Colors

Name
colorBackground
Type
string
Description
Main background color.
Name
colorBackgroundSecondary
Type
string
Description
Secondary/muted backgrounds.

Text Colors

Name
colorText
Type
string
Description
Primary text color.
Name
colorTextSecondary
Type
string
Description
Secondary/muted text.

Semantic Colors

Name
colorSuccess
Type
string
Description
Success states (checkmarks, confirmations).
Name
colorError
Type
string
Description
Error states (validation, failures).
Name
colorWarning
Type
string
Description
Warning states.

UI Colors

Name
colorBorder
Type
string
Description
Border color for inputs, cards.
Name
colorIcon
Type
string
Description
Icon fill color.

Typography

Name
fontFamily
Type
string
Description
Font stack for all text. The font must be loaded on your page.

variables: {
  fontFamily: '"Inter", -apple-system, BlinkMacSystemFont, sans-serif',
}

Sizing

Name
borderRadius
Type
string
Description
Base border radius (affects all elements).
Name
buttonHeight
Type
string
Description
Height of buttons.
Name
inputHeight
Type
string
Description
Height of input fields.
Name
spacingUnit
Type
string
Description
Base spacing unit (multiplied for gaps).

Common Examples

Brand Colors:

variables: { colorPrimary: '#4f46e5' }

Rounded Design:

variables: { borderRadius: '16px' }

Pill Buttons:

variables: { borderRadius: '9999px' }

Custom Typography:

variables: { fontFamily: '"Poppins", system-ui, sans-serif' }

Warm Color Scheme:

variables: {
  colorPrimary: '#f59e0b',
  colorBackground: '#fffbeb',
  colorBackgroundSecondary: '#fef3c7',
  colorText: '#78350f',
  colorBorder: '#fcd34d',
}

Dark with Custom Accent:

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  theme: 'dark',
  variables: {
    colorPrimary: '#f472b6', // Pink accent
  },
};

CSS Custom Properties

Variables map to CSS custom properties:

Variable	CSS Property
`colorPrimary`	`--qariyb-color-primary`
`colorBackground`	`--qariyb-color-background`
`colorText`	`--qariyb-color-text`
`borderRadius`	`--qariyb-border-radius`

These are applied to the component's Shadow DOM and can be inspected in DevTools.

Component Rules

Rules provide CSS class-level control for fine-grained styling beyond variables.

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  rules: {
    '.Button--primary': {
      textTransform: 'uppercase',
      letterSpacing: '0.05em',
    },
  },
};

Properties use camelCase and are converted to kebab-case CSS.

Available CSS Classes

Containers

Class	Description
`.Container`	Main wrapper element
`.Section`	Section wrapper

Buttons

Class	Description
`.Button`	All buttons
`.Button--primary`	Primary action (Continue, Pay)
`.Button--secondary`	Secondary action (Back)
`.Button--sm`	Small variant
`.Button--lg`	Large variant

rules: {
  '.Button--primary': {
    textTransform: 'uppercase',
    letterSpacing: '0.1em',
    boxShadow: '0 4px 14px rgba(16, 185, 129, 0.4)',
  },
}

Inputs

Class	Description
`.Input`	Text inputs, selects, textareas
`.Input--error`	Input with validation error
`.Label`	Input labels

Ticket Rows

Class	Description
`.TicketRow`	Ticket item container
`.TicketRow--selected`	Has quantity > 0
`.TicketRow--soldOut`	Sold out ticket
`.TicketName`	Ticket name text
`.TicketPrice`	Price display
`.TicketDescription`	Description text

rules: {
  '.TicketRow': {
    padding: '20px',
    marginBottom: '12px',
  },
  '.TicketRow--selected': {
    borderWidth: '2px',
    backgroundColor: 'rgba(16, 185, 129, 0.05)',
  },
}

Quantity Controls

Class	Description
`.QuantityControl`	Wrapper for +/- and value
`.QuantityButton`	+/- buttons
`.QuantityValue`	Current quantity number

rules: {
  '.QuantityButton': {
    width: '44px',
    height: '44px',
    borderRadius: '50%',
  },
}

Order Summary

Class	Description
`.OrderSummary`	Summary container
`.SummaryRow`	Line item row
`.SummaryTotal`	Total row

Modal

Class	Description
`.Modal`	Modal container
`.ModalOverlay`	Backdrop
`.ModalClose`	Close button

rules: {
  '.Modal': {
    maxWidth: '540px',
    borderRadius: '20px',
  },
  '.ModalOverlay': {
    backgroundColor: 'rgba(0, 0, 0, 0.6)',
    backdropFilter: 'blur(8px)',
  },
}

Loading & State Screens

Class	Description
`.Loading`	Loading container
`.Spinner`	Spinning loader
`.Skeleton`	Skeleton placeholder
`.Success`	Success state container
`.Error`	Error state container

Event Card

Class	Description
`.EventCard`	Card container
`.EventImage`	Cover image
`.EventTitle`	Event title
`.EventDate`	Date/time
`.EventLocation`	Location/venue
`.EventFeatures`	Feature icons

Supported CSS Properties

Rules support these properties (camelCase):

Display: display
Box Model: padding, margin, width, height, minWidth, maxWidth
Border: border, borderWidth, borderColor, borderRadius, borderStyle
Background: background, backgroundColor, backgroundImage
Typography: color, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textAlign, textTransform
Flexbox: flexDirection, justifyContent, alignItems, gap
Position: position, top, right, bottom, left
Effects: boxShadow, opacity, transform, transition

Complete Example

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  theme: 'light',
  variables: {
    colorPrimary: '#4f46e5',
    borderRadius: '12px',
  },
  rules: {
    // Buttons
    '.Button--primary': {
      textTransform: 'uppercase',
      letterSpacing: '0.1em',
      fontWeight: '700',
      boxShadow: '0 4px 14px rgba(79, 70, 229, 0.35)',
    },
    '.Button--secondary': {
      borderWidth: '2px',
    },

    // Inputs
    '.Input': {
      borderWidth: '2px',
      transition: 'border-color 0.15s ease',
    },
    '.Label': {
      fontWeight: '500',
      marginBottom: '8px',
    },

    // Tickets
    '.TicketRow': {
      padding: '24px',
      marginBottom: '16px',
    },
    '.TicketRow--selected': {
      borderWidth: '2px',
      backgroundColor: 'rgba(79, 70, 229, 0.04)',
    },
    '.TicketName': {
      fontSize: '1.125rem',
      fontWeight: '600',
    },

    // Quantity
    '.QuantityButton': {
      borderRadius: '50%',
      width: '44px',
      height: '44px',
    },

    // Summary
    '.OrderSummary': {
      backgroundColor: '#f5f3ff',
      borderRadius: '16px',
    },
    '.SummaryTotal': {
      fontSize: '1.25rem',
    },

    // Event cards
    '.EventCard': {
      boxShadow: '0 4px 20px rgba(0, 0, 0, 0.08)',
    },
    '.EventImage': {
      height: '180px',
    },
  },
};

TypeScript

Import types for configuration:

import type {
  QariybConfig,
  ThemePreset,
  ThemeVariableOverrides,
} from '@qariyb/js';

const theme: ThemePreset = 'dark';

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  theme,
  variables: {
    colorPrimary: '#8b5cf6',
  },
} satisfies QariybConfig;

Accent Color Shorthand

For simple color customization, use the accent-color attribute:

<qariyb-checkout
  event-id="01HW..."
  accent-color="#4f46e5"
></qariyb-checkout>

This is equivalent to:

variables: {
  colorPrimary: '#4f46e5',
}

Why Shadow DOM?

The widget uses Shadow DOM to encapsulate its styles. This ensures consistent appearance regardless of your page's CSS. Use the variables and rules configuration instead of external CSS:

// External CSS won't work - can't pierce Shadow DOM
// qariyb-checkout .Button { background: red; }

// Use configuration instead
window.QariybConfig = {
  publishableKey: 'pk_live_...',
  rules: {
    '.Button--primary': { background: 'red' },
  },
};