Payroo Payroll Components

Payroo payroll components provides you with the building blocks to create secure and efficient embedded payroll solutions. Designed with modern web technologies, this library ensures seamless integration into your payroll systems while prioritizing security, performance, and developer experience.

By using Payroo payroll components, you can focus on delivering exceptional payroll experiences without worrying about the underlying complexities of embedded environments.

Installation

Node package manager

1. Install the package

npm install @payroo-group/payroll-components --save

2. Import the components you need in your project

import { PayrollComponents } from '@payroo-group/payroll-components';

Importing Styles

The component library requires styles to be imported in your application. Import the CSS file in your application entry point:

import '@payroo-group/payroll-components/styles.css';

This imports all component styles and makes them available throughout your application. The styles are scoped using CSS Modules to prevent conflicts with your existing styles.

Quick Start

import { PayrollComponents, CompanyOverviewComponent } from '@payroo-group/payroll-components';

// First intiialize the core
const core = new PayrollComponents({
  environment: "sandbox",
  onSessionCreate: handleSessionCreate, // Provided function should call your backend to create a session
});

// Create the company overview component and mount it to the container
const component = new CompanyOverviewComponent(core, {
companyId: "78cc8d2b-8cae-4cbe-ba00-1103a275e1a8",
});
component.mount("#company-overview-container");

Requirements

1. A Payroo sandbox or production account
2. Payroo partner API credentials
3. A backend service to create and manage sessions securely

Check our documentation for detailed setup instructions and examples.

Browser Support

• Chrome: >= 73
• Firefox: >= 67
• Safari: >= 12.1
• Edge: >= 79

Customization

The Payroo Embedded Components library provides extensive customization options through CSS Custom Properties (CSS Variables). All variables are prefixed with --payroo- to prevent conflicts with your application's styles.

The library uses CSS Modules internally for scoped styling, ensuring that component styles don't leak into your application. Only the CSS variables provide customization hooks, giving you full control over colors, typography, spacing, and more while maintaining the integrity of component functionality.

Quick Customization Example

Override CSS variables in your application's CSS file to customize the components:

/* app.css */
:root {
  /* Change primary color from black to your brand color */
  --payroo-primary: #1e40af;

  /* Update success color */
  --payroo-success: #10b981;

  /* Adjust border radius for softer UI */
  --payroo-radius-sm: 8px;

  /* Update font family */
  --payroo-font-family-normal: 'Inter', system-ui, sans-serif;
}

CSS Variables Reference

The library uses CSS variables organized into the following categories:

Core Colors

| Variable | Default | Description | |----------|---------|-------------| | --payroo-primary | #000000 | Primary UI color (black) | | --payroo-secondary | #2196f3 | Secondary accent color (blue) | | --payroo-white | #ffffff | White color | | --payroo-bg-color | var(--payroo-white) | Background color |

Semantic Colors

| Variable | Default | Usage | |----------|---------|-------| | --payroo-disabled | var(--payroo-gray-200) | Disabled state background | | --payroo-placeholder | var(--payroo-gray-400) | Placeholder text color | | --payroo-accent-light | var(--payroo-green-light) | Light accent background | | --payroo-error | #ff2725 | Error states and messages | | --payroo-success | var(--payroo-green) | Success states | | --payroo-info | #0099fa | Informational messages | | --payroo-warning | #ff9100 | Warning states |

Text Colors

| Variable | Default | Usage | |----------|---------|-------| | --payroo-text | #222222 | Primary text color | | --payroo-text-body | #333333 | Body text color | | --payroo-text-light | #808080 | Secondary/light text |

Typography

Font Sizes:

| Variable | Default | |----------|---------| | --payroo-font-size-sm | 12px | | --payroo-font-size-md | 14px | | --payroo-font-size-lg | 18px | | --payroo-font-size-xl | 20px | | --payroo-font-size-xxl | 24px |

Line Heights:

| Variable | Default | |----------|---------| | --payroo-line-height-sm | 16px | | --payroo-line-height-md | 20px | | --payroo-line-height-lg | 26px | | --payroo-line-height-xl | 34px |

Font Weights:

| Variable | Default | |----------|---------| | --payroo-font-weight-normal | 400 | | --payroo-font-weight-medium | 500 | | --payroo-font-weight-bold | 700 |

Font Family:

| Variable | Default | |----------|---------| | --payroo-font-family-normal | system-ui, -apple-system, BlinkMacSystemFont, sans-serif, Inter |

Spacing System

Space Values (padding/margins):

| Variable | Default | Usage | |----------|---------|-------| | --payroo-space-xs | 6px | Extra small spacing | | --payroo-space-sm | 8px | Small spacing | | --payroo-space-md | 12px | Medium spacing | | --payroo-space-lg | 24px | Large spacing | | --payroo-space-xl | 48px | Extra large spacing |

Gap Values (flexbox/grid gaps):

| Variable | Default | |----------|---------| | --payroo-gap-xs | 2px | | --payroo-gap-sm | 4px | | --payroo-gap-md | 8px | | --payroo-gap-lg | 16px | | --payroo-gap-xl | 24px |

Border System

Border Radius:

| Variable | Default | Usage | |----------|---------|-------| | --payroo-radius-xs | 2px | Minimal rounding | | --payroo-radius-sm | 4px | Small rounding (inputs, buttons) | | --payroo-radius-md | 8px | Medium rounding | | --payroo-radius-lg | 12px | Large rounding | | --payroo-radius-xl | 24px | Extra large rounding |

Border Widths:

| Variable | Default | |----------|---------| | --payroo-border-width-thin | 1px | | --payroo-border-width-medium | 2px | | --payroo-border-width-thick | 3px |

Border Styles:

| Variable | Default | |----------|---------| | --payroo-border-style-solid | solid | | --payroo-border-style-dashed | dashed | | --payroo-border-style-dotted | dotted |

Border Colors:

| Variable | Default | Usage | |----------|---------|-------| | --payroo-border-color | var(--payroo-gray-200) | Default border color | | --payroo-border-color-light | var(--payroo-gray-100) | Light borders | | --payroo-border-color-dark | var(--payroo-gray-300) | Dark borders | | --payroo-border-color-primary | var(--payroo-primary) | Primary borders | | --payroo-border-color-secondary | var(--payroo-secondary) | Secondary borders | | --payroo-border-color-success | var(--payroo-success) | Success borders | | --payroo-border-color-error | var(--payroo-error) | Error borders | | --payroo-border-color-warning | var(--payroo-warning) | Warning borders | | --payroo-border-color-info | var(--payroo-info) | Info borders |

Customization Examples

Example 1: Match Your Brand Colors

:root {
  /* Your brand colors */
  --payroo-primary: #6366f1;              /* Indigo primary */
  --payroo-success: #10b981;              /* Emerald success */
  --payroo-error: #ef4444;                /* Red error */
  --payroo-secondary: #8b5cf6;            /* Purple secondary */

  /* Adjust text for better contrast */
  --payroo-text: #1f2937;
  --payroo-text-light: #6b7280;
}

Example 2: Softer UI with Rounded Corners

:root {
  --payroo-radius-sm: 8px;
  --payroo-radius-md: 12px;
  --payroo-radius-lg: 16px;
  --payroo-button-radius: 24px;  /* Pill-shaped buttons */
}

Example 3: High-Contrast Accessible Theme

:root {
  /* High contrast colors */
  --payroo-primary: #000000;
  --payroo-text: #000000;
  --payroo-bg-color: #ffffff;

  /* Thicker borders for visibility */
  --payroo-border-width-thin: 2px;
  --payroo-border-color: #000000;

  /* Larger text */
  --payroo-font-size-sm: 14px;
  --payroo-font-size-md: 16px;
  --payroo-font-size-lg: 20px;
}

Example 4: Dark Mode Support

@media (prefers-color-scheme: dark) {
  :root {
    --payroo-primary: #ffffff;
    --payroo-bg-color: #1f2937;
    --payroo-text: #f9fafb;
    --payroo-text-light: #d1d5db;
    --payroo-border-color: #374151;
    --payroo-disabled: #374151;
    --payroo-gray-50: #374151;
  }
}

Example 5: Custom Spacing Scale

@media screen and (min-width: 1024px) {
  :root {
    /* Increase spacing for larger screens */
    --payroo-space-md: 16px;
    --payroo-space-lg: 32px;
    --payroo-gap-md: 12px;
    --payroo-gap-lg: 24px;
  }
}

Customization Methods

Method 1: Global CSS Overrides

Override variables in your application's CSS file:

/* app.css */
:root {
  --payroo-primary: #1e40af;
  --payroo-success: #10b981;
  --payroo-radius-sm: 8px;
}

Import order matters. Load your custom CSS after the component styles:

// main.tsx
import '@payroo-group/payroll-components/styles.css';
import './app.css';  // Your overrides

Method 2: Scoped Container Overrides

Apply custom variables only to Payroo components by scoping to a container:

/* Only affects components inside .payroo-container */
.payroo-container {
  --payroo-primary: #7c3aed;
  --payroo-success: #059669;
  --payroo-border-color: #d1d5db;
}

// Mount components inside the scoped container
const container = document.querySelector('.payroo-container');
new CompanyRegistrationComponent(core, options).mount('.payroo-container');

Method 3: Runtime Theme Switching

Implement dynamic theme switching with JavaScript:

function applyTheme(theme) {
  const root = document.documentElement;

  if (theme === 'dark') {
    root.style.setProperty('--payroo-primary', '#ffffff');
    root.style.setProperty('--payroo-bg-color', '#1f2937');
    root.style.setProperty('--payroo-text', '#f9fafb');
    root.style.setProperty('--payroo-border-color', '#374151');
  } else {
    root.style.setProperty('--payroo-primary', '#000000');
    root.style.setProperty('--payroo-bg-color', '#ffffff');
    root.style.setProperty('--payroo-text', '#222222');
    root.style.setProperty('--payroo-border-color', '#e5e5e5');
  }
}

// Toggle themes
applyTheme('dark');

Support

For questions, issues, or support regarding embedded payroll integration, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information