HireControl UI Components

A flexible, customizable React component library for job search interfaces with integrated maps and filtering.

Features

• 🗺️ Interactive Map Integration - Google Maps with job location markers
• 🔍 Advanced Filtering - Multi-faceted search with dynamic counts
• 📱 Mobile Responsive - Tab-based mobile interface
• 🎨 Fully Customizable - Override any component with your own
• ⚡ Performance Optimized - Lazy loading and efficient rendering
• 🎯 Type Safe - TypeScript support
• 🧩 Modular Architecture - Use what you need

Installation

npm install @hirecontrol/hc-ui-components

Quick Start

import { HireControlMap } from '@hirecontrol/hc-ui-components';

function App() {
  return (
    <HireControlMap
      googleMapsApiKey="your-api-key"
      siteConfiguration={siteConfig}
      listings={listings}
      entities={entities}
    />
  );
}

Component Customization

NEW! Override any component to customize the UI while preserving all business logic:

import { HireControlMap } from '@hirecontrol/hc-ui-components';
import MyCustomFilter from './MyCustomFilter';
import MyCustomListItem from './MyCustomListItem';

<HireControlMap
  googleMapsApiKey="your-api-key"
  siteConfiguration={siteConfig}
  listings={listings}
  entities={entities}
  components={{
    Filter: MyCustomFilter,
    ListItem: MyCustomListItem,
    MapMarker: MyCustomMapMarker,
    // Override any component you want
  }}
/>

Available Components

• Map Components: MapList, MapTabs, Map, MapMarker, PlaceMarker, InfoWindowCard
• Filter Components: Filter, FilterItem, FilterSearch, FilterLocation, FilterCommute
• List Components: ListItem, ItemsList, ListHeader, FieldMapperDesktop, FieldMapperMobile
• Accordion Components: Accordion, FiltersAccordion, FilterItemAccordion, MapAccordionItem
• Button Components: Button, ButtonGroupApply, ItemsPill, ShowAllButton
• Card Components: Card, CardFilter
• Dialog Components: ApplyDialog
• Utility Components: Grid, Icon

See Component Customization Guide for detailed documentation.

Props

Required Props

| Prop | Type | Description | |------|------|-------------| | googleMapsApiKey | string | Google Maps API key | | siteConfiguration | object | Site configuration object | | listings | array | Job listings data |

Optional Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | entities | array | [] | Entity/location data | | components | object | {} | Component overrides | | containerStyle | object | { height: '100vh' } | Container styling | | hideMap | boolean | false | Hide map view | | hideFilters | boolean | false | Hide filter panel | | filterConfig | object | {} | Filter configuration | | trackEvent | function | Console log | Analytics tracking | | navigateToDetails | function | null | Custom navigation handler | | Link | component | null | Custom Link component | | defaultFilters | object | null | Initial filter state | | hiddenFilters | array | null | Filters to hide |

See full prop documentation in API Reference.

Site Configuration

const siteConfiguration = {
  colors: {
    primary: '#3B82F6',
    primaryDark: '#1E40AF',
    secondary: '#10B981',
    secondaryDark: '#047857',
    uiText: '#1F2937',
    uiAccent: '#6B7280',
    borderDefault: '#E5E7EB'
  },
  showMap: true,
  mapPosition: 'bottom', // 'top' or 'bottom'
  fieldsShown: ['title', 'category', 'entityName', 'location'],
  fieldNames: {
    title: 'Job Title',
    category: 'Category',
    entityName: 'Company',
    location: 'Location'
  },
  pointsOfInterestConfig: {
    placeMappings: {},
    showAtZoomLevel: 12,
    placeMarkerColors: {},
    placeMarkerSize: 30
  }
};

Advanced Usage

Using Component Hooks

import { useComponents } from '@hirecontrol/hc-ui-components';

const MyCustomComponent = () => {
  const { Filter, ListItem } = useComponents();
  
  return (
    <div>
      <Filter {...filterProps} />
      <ListItem {...itemProps} />
    </div>
  );
};

Extending Default Components

import { defaultComponents } from '@hirecontrol/hc-ui-components';

const EnhancedFilter = (props) => {
  const DefaultFilter = defaultComponents.Filter;
  
  return (
    <div className="enhanced-wrapper">
      <DefaultFilter {...props} />
      <div className="custom-addition">Extra content</div>
    </div>
  );
};

Higher-Order Component Pattern

import { withComponents } from '@hirecontrol/hc-ui-components';

const MyContainer = ({ Filter, ListItem, data }) => {
  return (
    <div>
      <Filter />
      {data.map(item => <ListItem key={item.id} item={item} />)}
    </div>
  );
};

export default withComponents(['Filter', 'ListItem'])(MyContainer);

Styling

The library uses Tailwind CSS with a custom hc- prefix to avoid conflicts:

<div className="hc-bg-primary hc-text-white hc-p-4 hc-rounded-lg">
  Custom styled element
</div>

Customizing Styles

1. Override components with your own styling
2. Use filterConfig.classNames to inject custom classes
3. Wrap with styled containers around default components

Examples

Custom Filter with Analytics

const AnalyticsFilter = (props) => {
  const { Filter } = useComponents();
  
  useEffect(() => {
    analytics.track('Filter Panel Viewed');
  }, []);
  
  const handleFilterChange = (filters) => {
    analytics.track('Filters Applied', { filters });
    props.setSelectedFilters(filters);
  };
  
  return <Filter {...props} setSelectedFilters={handleFilterChange} />;
};

Custom List Item with Favorites

const CustomListItem = ({ item, favorites, handleSettingFavorites, ...props }) => {
  const isFavorite = favorites.includes(item.id);
  
  return (
    <div className="hc-border hc-rounded-lg hc-p-4 hc-hover:shadow-lg">
      <div className="hc-flex hc-justify-between">
        <h3>{item.fields.title}</h3>
        <button 
          onClick={(e) => {
            e.stopPropagation();
            handleSettingFavorites(item.id);
          }}
        >
          {isFavorite ? '❤️' : '🤍'}
        </button>
      </div>
      <p className="hc-text-gray-600">{item.fields.category}</p>
      <p className="hc-text-sm">{item.mapDetails?.entityDisplayName}</p>
    </div>
  );
};

TypeScript Support

The library includes TypeScript definitions:

import { HireControlMap, ComponentOverrides } from '@hirecontrol/hc-ui-components';

const customComponents: ComponentOverrides = {
  Filter: MyCustomFilter,
  ListItem: MyCustomListItem,
};

<HireControlMap
  googleMapsApiKey={apiKey}
  siteConfiguration={config}
  listings={listings}
  components={customComponents}
/>

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Performance

• Lazy loading of Google Maps
• Virtual scrolling for large lists
• Debounced search inputs
• Optimized re-renders with React.memo
• Efficient clustering for map markers

Troubleshooting

Google Maps Not Loading

• Verify API key is correct
• Check API key has Maps JavaScript API enabled
• Ensure domain is whitelisted in Google Console

Custom Components Not Rendering

• Verify component name matches exactly (case-sensitive)
• Ensure all required props are handled
• Check browser console for errors

Styling Conflicts

• Use the hc- prefix for Tailwind classes
• Check CSS specificity
• Use browser dev tools to inspect styles

See Troubleshooting Guide for more help.

Documentation

• Component Customization Guide - Detailed customization docs
• Component Reference - Quick reference for all components
• API Reference - Complete prop documentation
• Examples - Code examples and use cases

Contributing

Contributions are welcome! Please read our Contributing Guide first.

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues: https://github.com/hirecontrol/hc-ui-components/issues
• Documentation: https://docs.hirecontrol.com
• Email: [email protected]