react-french-ssn

React component for French Social Security Numbers (NIR)

🚀 Overview

react-french-ssn is a React library specialized in handling French Social Security Numbers (NIR - Numéro d'Identification au Répertoire). It provides a SocialSecurityInput component with automatic formatting, validation, and advanced features, built with TypeScript for an optimal development experience.

✨ Features

• 🔢 Automatic Formatting - Guided input by Social Security Number segments
• ✅ Built-in Validation - Automatic control key verification
• 📋 Copy Button - Easy copying of the complete number to clipboard
• 🎯 TypeScript First - Fully typed with complete type definitions
• 🎨 Modular Styling - CSS Modules for encapsulated and customizable styling
• 🌙 Dark Mode Support - Automatic dark mode detection
• 🧪 Complete Testing - Jest and React Testing Library with high coverage
• 📚 Interactive Documentation - Storybook to explore the component
• 🔧 Code Quality - ESLint, Prettier, and strict TypeScript configuration

📦 Installation

npm install react-french-ssn

yarn add react-french-ssn

pnpm add react-french-ssn

🎯 Quick Start

import React from 'react';
import { SocialSecurityInput } from 'react-french-ssn';

function App() {
  return (
    <SocialSecurityInput 
      label="Social Security Number"
      placeholder="269054958815780"
      onChange={(value) => console.log(value)}
    />
  );
}

📋 Examples

Basic Usage

import { SocialSecurityInput } from 'react-french-ssn';

function BasicExample() {
  const [ssn, setSsn] = useState('');

  return (
    <SocialSecurityInput
      label="Numéro de sécurité sociale"
      placeholder="269054958815780"
      value={ssn}
      onChange={setSsn}
    />
  );
}

With Error Handling

import { SocialSecurityInput } from 'react-french-ssn';

function ErrorExample() {
  const [ssn, setSsn] = useState('');
  const [error, setError] = useState('');

  const handleChange = (value) => {
    setSsn(value);
    if (value.length === 15) {
      setError('');
    } else if (value.length > 0) {
      setError('Le numéro doit contenir 15 chiffres');
    }
  };

  return (
    <SocialSecurityInput
      label="Numéro de sécurité sociale"
      value={ssn}
      onChange={handleChange}
      error={error}
    />
  );
}

With Copy Button

import { SocialSecurityInput } from 'react-french-ssn';

function CopyExample() {
  return (
    <SocialSecurityInput
      label="Numéro de sécurité sociale"
      placeholder="269054958815780"
      showCopyButton={true}
      onChange={(value) => console.log('SSN:', value)}
    />
  );
}

Custom Styling

import { SocialSecurityInput } from 'react-french-ssn';
import './custom-styles.css';

function StyledExample() {
  return (
    <SocialSecurityInput
      label="Numéro de sécurité sociale"
      className="custom-ssn-input"
      showCopyButton={true}
      onChange={(value) => console.log(value)}
    />
  );
}

Internationalization

import { SocialSecurityInput } from 'react-french-ssn';

function I18nExample() {
  return (
    <SocialSecurityInput
      label="Social Security Number"
      placeholder="269054958815780"
      showCopyButton={true}
      texts={{
        description: 'Enter your French social security number (15 digits)',
        fieldDescriptions: {
          sex: 'Gender (1 for male, 2 for female)',
          year: 'Birth year (last 2 digits)',
          month: 'Birth month (01 to 12)',
          department: 'Birth department (2 digits or 2A/2B)',
          insee: 'INSEE municipality code (3 digits)',
          order: 'Order number (3 digits)',
          controlKey: 'Control key (calculated automatically)'
        },
        copyButton: {
          copy: 'Copy',
          copied: 'Copied!',
          copyLabel: 'Copy the complete social security number',
          copiedLabel: 'Number copied successfully'
        }
      }}
      onChange={(value) => console.log(value)}
    />
  );
}

🧩 Main Component

SocialSecurityInput

The main component of this library, specifically designed for French Social Security Number input. It automatically divides input into logical segments and calculates the control key.

import { SocialSecurityInput } from 'react-french-ssn';

<SocialSecurityInput 
  label="Social Security Number"
  placeholder="269054958815780"
  value={ssnValue}
  onChange={handleSSNChange}
  error={errorMessage}
  showCopyButton={true}
  disabled={false}
  className="custom-class"
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | label | string | 'Social Security Number' | Field label | | placeholder | string | '269054958815780' | Placeholder text | | value | string | - | Controlled value | | onChange | (value: string) => void | - | Change callback | | error | string | - | Error message | | disabled | boolean | false | Disabled state | | className | string | '' | Custom CSS classes | | showCopyButton | boolean | false | Show copy button |

Optional ThemeProvider

Optional context provider for theme configuration (not required for basic usage).

import { ThemeProvider, SocialSecurityInput } from 'react-french-ssn';

<ThemeProvider theme={{ colors: { primary: '#custom-color' } }}>
  <SocialSecurityInput />
</ThemeProvider>

🎣 Custom Hook

useSocialSecurityInput

Internal hook that handles the formatting and validation logic for Social Security Numbers.

import { useSocialSecurityInput } from 'react-french-ssn';

const { values, handlers, placeholders } = useSocialSecurityInput({
  onChange: handleChange,
  placeholder: '269054958815780',
  value: currentValue,
});

🛠️ Utilities

Global Configuration

import { setGlobalConfig, getGlobalConfig, resetGlobalConfig } from 'react-french-ssn';

setGlobalConfig({
  theme: 'light',
  locale: 'fr-FR',
});

const config = getGlobalConfig();

CSS Variables

import { getCSSVariable, createCSSVariables } from 'react-french-ssn';

const primaryColor = getCSSVariable('--primary-color');
const variables = createCSSVariables({
  '--primary-color': '#007bff',
  '--secondary-color': '#6c757d'
});

🎯 Use Cases

This component is perfect for:

• Administrative Forms - Social Security Number input
• HR Applications - Employee data management
• Healthcare Systems - Patient identification
• Government Applications - Public services online

📝 TypeScript Support

This library is fully built with TypeScript and provides complete type definitions.

import type { 
  SocialSecurityInputProps, 
  GlobalConfig, 
  ThemeConfig 
} from 'react-french-ssn';

const props: SocialSecurityInputProps = {
  label: 'Social Security Number',
  onChange: (value: string) => console.log(value)
};

📄 License

MIT © JatoCool Company

🎮 Testez le composant interactivement

🚀 Démo en ligne

🎮 Testez le composant directement dans votre navigateur

Cette démo interactive vous permet de :

• ✅ Tester le formatage automatique en temps réel
• ✅ Voir la validation et les messages d'erreur
• ✅ Comprendre la structure du numéro de sécurité sociale
• ✅ Essayer différents exemples de numéros

📦 Démo CodeSandbox

Cliquez sur le bouton ci-dessus pour tester le composant dans CodeSandbox !

🎯 Fonctionnalités à tester

• ✅ Formatage automatique - Tapez 269054958815780 pour voir le découpage
• ✅ Validation en temps réel - Essayez des numéros invalides
• ✅ Bouton de copie - Copiez le numéro formaté
• ✅ Accessibilité - Testez avec le clavier et lecteurs d'écran
• ✅ Mode sombre - Détection automatique du thème

🏠 Démo locale avec Storybook

# Cloner le repository
git clone https://github.com/Johanna1506/ui.git
cd ui

# Installer les dépendances
npm install

# Lancer Storybook
npm run storybook

Puis ouvrez http://localhost:6006 dans votre navigateur.

📚 Stories disponibles

• Interactive - Composant entièrement interactif pour tester toutes les fonctionnalités
• Default - Version basique du composant
• WithLabel - Avec label personnalisé
• WithError - Avec gestion d'erreur
• Disabled - État désactivé
• WithCopyButton - Avec bouton de copie
• WithCustomTexts - Textes personnalisés

🔗 Links

• NPM Package
• GitHub Repository

Specialized in French Social Security Numbers
Built with ❤️ by JatoCool Company