🌍 DataForge React Components

A comprehensive React component library providing location-based selectors, utilities, and form components with real-time API data integration.

✨ Features

• 🌍 Real API Data - Live data from DataForge API
• 🔗 Smart Cascading - Components work intelligently together
• 🔍 Searchable Dropdowns - Real-time filtering and search
• 🎯 Country-Based Filtering - Automatic filtering based on country selection
• 📱 Mobile Optimized - Responsive design with proper input types
• ♿ Accessible - ARIA labels and keyboard navigation
• 🎨 Customizable - CSS classes and styling options
• 📦 Zero Configuration - Automatic API token management
• 🛡️ TypeScript Support - Full type definitions included

🚀 Quick Start

Installation

1npm install @data-forge-services/react-core

Basic Usage

1import React, { useState } from 'react';
2import { CountrySelect, StateSelect } from '@data-forge-services/react-core';
3import '@data-forge-services/react-core/dist/react-core.css';
4
5function App() {
6  const [country, setCountry] = useState('');
7  const [state, setState] = useState('');
8
9  const handleCountryChange = (newCountry) => {
10    setCountry(newCountry);
11    setState(''); // Reset state when country changes
12  };
13
14  return (
15    <div>
16      <CountrySelect
17        label="Country"
18        value={country}
19        onChange={handleCountryChange}
20        searchable={true}
21      />
22      
23      <StateSelect
24        label="State/Province"
25        value={state}
26        onChange={setState}
27        country={country}
28        searchable={true}
29      />
30    </div>
31  );
32}

📦 Available Components

📍 Location Hierarchy Components

RegionSelect

Select world regions (Asia, Europe, Americas, etc.)

1import { RegionSelect } from '@data-forge-services/react-core';
2
3<RegionSelect
4  label="Region"
5  value={region}
6  onChange={setRegion}
7  searchable={true}
8  onSelected={(regionObject) => console.log('Selected:', regionObject)}
9/>

SubregionSelect

Select subregions within a selected region

1import { SubregionSelect } from '@data-forge-services/react-core';
2
3<SubregionSelect
4  label="Subregion"
5  value={subregion}
6  onChange={setSubregion}
7  region={region}  // Filter by selected region
8  searchable={true}
9/>

CountrySelect

Select countries with optional region/subregion filtering

1import { CountrySelect } from '@data-forge-services/react-core';
2
3<CountrySelect
4  label="Country"
5  value={country}
6  onChange={setCountry}
7  region={region}        // Optional: filter by region
8  subregion={subregion}  // Optional: filter by subregion
9  searchable={true}
10  onSelected={(countryObject) => {
11    console.log('Full country data:', countryObject);
12    // Use country data for other components
13  }}
14/>

StateSelect

Select states/provinces within a country

1import { StateSelect } from '@data-forge-services/react-core';
2
3<StateSelect
4  label="State/Province"
5  value={state}
6  onChange={setState}
7  country={country}  // Required for filtering
8  searchable={true}
9/>

CitySelect

Select cities within a country and state

1import { CitySelect } from '@data-forge-services/react-core';
2
3<CitySelect
4  label="City"
5  value={city}
6  onChange={setCity}
7  country={country}  // Required
8  state={state}      // Required
9  searchable={true}
10/>

🔧 Utility Components

TimezoneSelect

Select timezones with optional country filtering

1import { TimezoneSelect } from '@data-forge-services/react-core';
2
3<TimezoneSelect
4  label="Timezone"
5  value={timezone}
6  onChange={setTimezone}
7  country={country}  // Optional: filter by country
8  searchable={true}
9/>

CurrencySelect

Select currencies with optional country filtering

1import { CurrencySelect } from '@data-forge-services/react-core';
2
3<CurrencySelect
4  label="Currency"
5  value={currency}
6  onChange={setCurrency}
7  country={country}  // Optional: filter by country
8  searchable={true}
9/>

LanguageSelect

Select languages with optional country filtering

1import { LanguageSelect } from '@data-forge-services/react-core';
2
3<LanguageSelect
4  label="Language"
5  value={language}
6  onChange={setLanguage}
7  country={country}  // Optional: filter by country
8  searchable={true}
9/>

PhoneSelect

International phone number input with country code selection

1import { PhoneSelect } from '@data-forge-services/react-core';
2
3<PhoneSelect
4  label="Phone Number"
5  value={phone}
6  onChange={setPhone}
7  defaultCountryCode={country}  // Auto-set country code
8  required={true}
9/>

🏠 Address Components

AddressInput

Complete address form with integrated location components

1import { AddressInput } from '@data-forge-services/react-core';
2
3const [address, setAddress] = useState({
4  street1: '',
5  street2: '',
6  city: '',
7  state: '',
8  country: '',
9  postalCode: ''
10});
11
12<AddressInput
13  value={address}
14  onChange={setAddress}
15  locationSelectorsSearchable={true}
16  onAddressChange={(newAddress) => {
17    console.log('Address updated:', newAddress);
18  }}
19/>

🎯 Advanced Usage Examples

Complete Location Hierarchy

1import React, { useState, useCallback } from 'react';
2import {
3  RegionSelect,
4  SubregionSelect,
5  CountrySelect,
6  StateSelect,
7  CitySelect
8} from '@data-forge-services/react-core';
9
10function LocationForm() {
11  const [region, setRegion] = useState('');
12  const [subregion, setSubregion] = useState('');
13  const [country, setCountry] = useState('');
14  const [state, setState] = useState('');
15  const [city, setCity] = useState('');
16
17  // Cascade handlers that reset child values
18  const handleRegionChange = (newRegion) => {
19    setRegion(newRegion);
20    setSubregion('');
21    setCountry('');
22    setState('');
23    setCity('');
24  };
25
26  const handleSubregionChange = (newSubregion) => {
27    setSubregion(newSubregion);
28    setCountry('');
29    setState('');
30    setCity('');
31  };
32
33  const handleCountryChange = (newCountry) => {
34    setCountry(newCountry);
35    setState('');
36    setCity('');
37  };
38
39  const handleStateChange = (newState) => {
40    setState(newState);
41    setCity('');
42  };
43
44  return (
45    <div>
46      <RegionSelect
47        label="Region"
48        value={region}
49        onChange={handleRegionChange}
50        searchable={true}
51      />
52      
53      <SubregionSelect
54        label="Subregion"
55        value={subregion}
56        onChange={handleSubregionChange}
57        region={region}
58        searchable={true}
59      />
60      
61      <CountrySelect
62        label="Country"
63        value={country}
64        onChange={handleCountryChange}
65        region={region}
66        subregion={subregion}
67        searchable={true}
68      />
69      
70      <StateSelect
71        label="State/Province"
72        value={state}
73        onChange={handleStateChange}
74        country={country}
75        searchable={true}
76      />
77      
78      <CitySelect
79        label="City"
80        value={city}
81        onChange={setCity}
82        country={country}
83        state={state}
84        searchable={true}
85      />
86    </div>
87  );
88}

Country-Based Utility Filtering

1import React, { useState, useCallback } from 'react';
2import {
3  CountrySelect,
4  TimezoneSelect,
5  CurrencySelect,
6  LanguageSelect,
7  PhoneSelect
8} from '@data-forge-services/react-core';
9
10function CountryDependentForm() {
11  const [selectedCountry, setSelectedCountry] = useState(null);
12  const [timezone, setTimezone] = useState('');
13  const [currency, setCurrency] = useState('');
14  const [language, setLanguage] = useState('');
15  const [phone, setPhone] = useState('');
16
17  const handleCountrySelected = useCallback((countryObject) => {
18    setSelectedCountry(countryObject);
19    // Reset dependent values when country changes
20    setTimezone('');
21    setCurrency('');
22    setLanguage('');
23  }, []);
24
25  return (
26    <div>
27      <CountrySelect
28        label="Country"
29        value={selectedCountry?.id || ''}
30        onChange={(value) => setSelectedCountry({ id: value })}
31        onSelected={handleCountrySelected}
32        searchable={true}
33      />
34      
35      {/* These components will filter based on selected country */}
36      <TimezoneSelect
37        label="Timezone"
38        value={timezone}
39        onChange={setTimezone}
40        country={selectedCountry?.id}
41        searchable={true}
42      />
43      
44      <CurrencySelect
45        label="Currency"
46        value={currency}
47        onChange={setCurrency}
48        country={selectedCountry?.id}
49        searchable={true}
50      />
51      
52      <LanguageSelect
53        label="Language"
54        value={language}
55        onChange={setLanguage}
56        country={selectedCountry?.id}
57        searchable={true}
58      />
59      
60      <PhoneSelect
61        label="Phone Number"
62        value={phone}
63        onChange={setPhone}
64        defaultCountryCode={selectedCountry?.id}
65      />
66    </div>
67  );
68}

🔧 Component Props Reference

Common Props (All Components)

1interface CommonProps {
2  label?: string;                      // Display label
3  value?: string | number;             // Current selected value
4  onChange: (value: string) => void;   // Change handler
5  searchable?: boolean;                // Enable search functionality
6  disabled?: boolean;                  // Disable component
7  required?: boolean;                  // Mark as required field
8  placeholder?: string;                // Placeholder text
9  onSelected?: (item: object) => void; // Selection callback with full object
10}

Location Component Props

1interface RegionSelectProps extends CommonProps {}
2
3interface SubregionSelectProps extends CommonProps {
4  region?: string; // Filter by region
5}
6
7interface CountrySelectProps extends CommonProps {
8  region?: string;     // Filter by region
9  subregion?: string;  // Filter by subregion
10}
11
12interface StateSelectProps extends CommonProps {
13  country?: string; // Required for fetching states
14}
15
16interface CitySelectProps extends CommonProps {
17  country?: string; // Required for fetching cities
18  state?: string;   // Required for fetching cities
19}

Utility Component Props

1interface TimezoneSelectProps extends CommonProps {
2  country?: string; // Filter timezones by country
3}
4
5interface CurrencySelectProps extends CommonProps {
6  country?: string; // Filter currencies by country
7}
8
9interface LanguageSelectProps extends CommonProps {
10  country?: string; // Filter languages by country
11}
12
13interface PhoneSelectProps extends CommonProps {
14  defaultCountryCode?: string; // Auto-set country code
15}

Address Component Props

1interface AddressValue {
2  street1: string;
3  street2: string;
4  city: string;
5  state: string;
6  country: string;
7  postalCode: string;
8}
9
10interface AddressInputProps {
11  value: AddressValue;
12  onChange: (address: AddressValue) => void;
13  locationSelectorsSearchable?: boolean;
14  onAddressChange?: (address: AddressValue) => void;
15}

🎨 Styling

Default CSS

Import the included CSS file for default styling:

1import '@data-forge-services/react-core/dist/react-core.css';

CSS Classes

Available CSS classes for customization:

1/* Label styling */
2.fallback-label {
3  font-weight: 600;
4  margin-bottom: 4px;
5  font-size: 14px;
6  color: #333;
7}
8
9/* Select container */
10.fallback-select {
11  position: relative;
12  display: inline-block;
13  width: 100%;
14}
15
16/* Dropdown trigger */
17.fallback-select-trigger {
18  display: flex;
19  align-items: center;
20  padding: 8px 12px;
21  border: 1px solid #ccc;
22  border-radius: 4px;
23  background: #fff;
24  cursor: pointer;
25}
26
27/* Dropdown menu */
28.fallback-dropdown {
29  position: absolute;
30  top: 100%;
31  left: 0;
32  right: 0;
33  background: #fff;
34  border: 1px solid #ccc;
35  border-top: none;
36  max-height: 200px;
37  overflow-y: auto;
38  z-index: 1000;
39}
40
41/* Dropdown options */
42.fallback-option {
43  padding: 8px 12px;
44  cursor: pointer;
45  border-bottom: 1px solid #eee;
46}
47
48.fallback-option:hover {
49  background-color: #f5f5f5;
50}
51
52.fallback-option.selected {
53  background-color: #e3f2fd;
54  font-weight: bold;
55}

🔗 API Integration

Automatic Setup

Components automatically connect to the DataForge API. An API token is generated during installation:

1# Automatic during npm install
2npm install @data-forge-services/react-core

Manual Token Setup

If needed, manually set up the API token:

1npm run setup

Custom Configuration

For custom API endpoints or configuration:

1// This is handled automatically, but you can check the config
2import config from '@data-forge-services/react-core/src/location-selector/services.config.js';
3console.log('API Configuration:', config);

🔧 Requirements

• React: 18.0.0 or higher
• React DOM: 18.0.0 or higher
• Modern Browser: ES2020 support

📱 Mobile Support

Components are optimized for mobile devices:

• Responsive design - Works on all screen sizes
• Touch-friendly - Proper touch targets
• Mobile keyboards - Correct input types (tel, email, etc.)
• Accessibility - Screen reader support

🛠️ Development

Building from Source

1git clone https://github.com/Astra-Techno/DataForgeReactComponents.git
2cd DataForgeReactComponents
3npm install
4npm run build

Running Tests

1npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🐛 Issues & Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Documentation: GitHub Wiki

🙏 Acknowledgments

• DataForge API - For providing comprehensive location data
• libphonenumber-js - For phone number validation and formatting
• Flag Icons - For country flag representations
• React Community - For the amazing ecosystem

---

Made with ❤️ by Astra Techno