react-intials-avatar-generator 1.0.0

package/README.md

@@ -0,0 +1,240 @@
+# React Initials Avatar
+
+A lightweight, customizable React component for generating beautiful initials-based avatars. Perfect for user profiles, contact lists, and any application that needs elegant placeholder avatars.
+
+## Features
+
+- 🎨 Fully customizable colors, sizes, and styles
+- 🔤 Smart initials extraction from names
+- 📦 Zero dependencies (except React)
+- 🎯 TypeScript support
+- ⚡ Lightweight and performant
+- 🎭 Flexible styling options
+
+## Installation
+
+```bash
+npm install react-initials-avatar
+```
+
+or
+
+```bash
+yarn add react-initials-avatar
+```
+
+or
+
+```bash
+pnpm add react-initials-avatar
+```
+
+## Basic Usage
+
+```jsx
+import { InitialsAvatar } from 'react-initials-avatar';
+
+function App() {
+  return (
+    <InitialsAvatar name="John Doe" />
+  );
+}
+```
+
+## Props
+
+### Component Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | **required** | The full name to extract initials from |
+| `styles` | `StyleProps` | `{}` | Styling configuration object |
+| `options` | `InitialOptions` | `{}` | Options for initials extraction |
+
+### StyleProps
+
+Configure the visual appearance of the avatar:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `number` | `50` | Avatar size in pixels (width and height) |
+| `radius` | `number \| string` | `"50%"` | Border radius (use "50%" for circle, number for rounded square) |
+| `bgColor` | `string` | `"#4f46e5"` | Background color (any valid CSS color) |
+| `textColor` | `string` | `"#ffffff"` | Text color for initials |
+| `fontFamily` | `string` | `"inherit"` | Font family for the initials |
+| `fontSize` | `number` | `size * 0.4` | Font size in pixels (auto-calculated if not provided) |
+| `fontWeight` | `number \| string` | `600` | Font weight (100-900 or CSS keywords) |
+| `lineHeight` | `number \| string` | `size + "px"` | Line height for vertical centering |
+| `letterSpacing` | `number \| string` | `0` | Letter spacing in pixels or CSS units |
+
+### InitialOptions
+
+Control how initials are extracted from names:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `maxLength` | `number` | `Infinity` | Maximum number of initials to display |
+| `uppercase` | `boolean` | `true` | Convert initials to uppercase |
+| `fallback` | `string` | `""` | Fallback text when name is empty or invalid |
+
+## Examples
+
+### Basic Avatar
+
+```jsx
+<InitialsAvatar name="John Doe" />
+```
+
+### Custom Size and Colors
+
+```jsx
+<InitialsAvatar 
+  name="Jane Smith"
+  styles={{
+    size: 80,
+    bgColor: "#10b981",
+    textColor: "#ffffff"
+  }}
+/>
+```
+
+### Square Avatar with Rounded Corners
+
+```jsx
+<InitialsAvatar 
+  name="Alice Johnson"
+  styles={{
+    size: 60,
+    radius: 8,
+    bgColor: "#f59e0b"
+  }}
+/>
+```
+
+### Custom Font Styling
+
+```jsx
+<InitialsAvatar 
+  name="Bob Wilson"
+  styles={{
+    size: 100,
+    fontFamily: "Arial, sans-serif",
+    fontSize: 45,
+    fontWeight: 700,
+    letterSpacing: 2
+  }}
+/>
+```
+
+### Limit Initials Length
+
+```jsx
+<InitialsAvatar 
+  name="Christopher Alexander Montgomery"
+  options={{
+    maxLength: 2  // Will show "CA" instead of "CAM"
+  }}
+/>
+```
+
+### Lowercase Initials
+
+```jsx
+<InitialsAvatar 
+  name="David Brown"
+  options={{
+    uppercase: false
+  }}
+/>
+```
+
+### With Fallback
+
+```jsx
+<InitialsAvatar 
+  name=""
+  options={{
+    fallback: "?"
+  }}
+  styles={{
+    bgColor: "#6b7280"
+  }}
+/>
+```
+
+### Complete Custom Example
+
+```jsx
+<InitialsAvatar 
+  name="Emily Rose Parker"
+  styles={{
+    size: 120,
+    radius: "20%",
+    bgColor: "#8b5cf6",
+    textColor: "#fef3c7",
+    fontFamily: "Georgia, serif",
+    fontSize: 50,
+    fontWeight: 500,
+    letterSpacing: 3
+  }}
+  options={{
+    maxLength: 2,
+    uppercase: true
+  }}
+/>
+```
+
+## How Initials Are Extracted
+
+The component intelligently extracts initials from names:
+
+1. Removes special characters like hyphens, periods, and apostrophes
+2. Splits the name by spaces
+3. Takes the first letter of each word
+4. Applies the `maxLength` limit if specified
+5. Converts to uppercase by default (unless `uppercase: false`)
+
+**Examples:**
+- `"John Doe"` → `"JD"`
+- `"Mary-Jane Watson"` → `"MJW"`
+- `"Dr. James Smith Jr."` → `"DJSJ"`
+- `"Anne O'Brien"` → `"AOB"`
+
+## TypeScript Support
+
+The package includes full TypeScript definitions:
+
+```typescript
+import { InitialsAvatar } from 'react-initials-avatar';
+import type { StyleProps, InitialOptions } from 'react-initials-avatar';
+
+const styles: StyleProps = {
+  size: 60,
+  bgColor: "#3b82f6"
+};
+
+const options: InitialOptions = {
+  maxLength: 2,
+  uppercase: true
+};
+```
+
+## Browser Support
+
+Works in all modern browsers that support React 18+:
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © Ankit Kumar Pandey
+
+## Keywords
+
+react, avatar, initials, react-avatar, profile-avatar, user-avatar, placeholder-avatar, avatar-component

package/dist/react-initials-avatar.es.js

@@ -0,0 +1,55 @@
+import { jsx as u } from "react/jsx-runtime";
+const h = (t, s = {}) => {
+  const {
+    maxLength: i = 1 / 0,
+    uppercase: e = !0,
+    fallback: n = ""
+  } = s;
+  if (typeof t != "string") return n;
+  const r = t.trim();
+  if (!r) return n;
+  const o = r.replace(/[-.']/g, " ").replace(/[^a-zA-Z\s]/g, "").split(/\s+/).map((c) => c[0]).join("");
+  return e ? o.slice(0, i).toUpperCase() : o.slice(0, i);
+}, x = ({
+  name: t,
+  styles: s = {},
+  options: i = {}
+}) => {
+  const {
+    size: e = 50,
+    radius: n = "50%",
+    bgColor: r = "#4f46e5",
+    textColor: a = "#ffffff",
+    fontFamily: o = "inherit",
+    fontSize: c,
+    fontWeight: l = 600,
+    lineHeight: f,
+    letterSpacing: p = 0
+  } = s, g = h(t, i), d = c ?? e * 0.4;
+  return /* @__PURE__ */ u(
+    "div",
+    {
+      style: {
+        width: e,
+        height: e,
+        borderRadius: n,
+        backgroundColor: r,
+        color: a,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        fontFamily: o,
+        fontSize: d,
+        fontWeight: l,
+        lineHeight: f ?? `${e}px`,
+        letterSpacing: p,
+        userSelect: "none"
+      },
+      children: g
+    }
+  );
+};
+export {
+  x as InitialsAvatar,
+  h as getInitials
+};

package/dist/react-initials-avatar.umd.js

@@ -0,0 +1 @@
+(function(e,i){typeof exports=="object"&&typeof module<"u"?i(exports,require("react/jsx-runtime")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime"],i):(e=typeof globalThis<"u"?globalThis:e||self,i(e.ReactInitialsAvatar={},e["react/jsx-runtime"]))})(this,(function(e,i){"use strict";const l=(n,a={})=>{const{maxLength:r=1/0,uppercase:t=!0,fallback:s=""}=a;if(typeof n!="string")return s;const o=n.trim();if(!o)return s;const c=o.replace(/[-.']/g," ").replace(/[^a-zA-Z\s]/g,"").split(/\s+/).map(f=>f[0]).join("");return t?c.slice(0,r).toUpperCase():c.slice(0,r)},d=({name:n,styles:a={},options:r={}})=>{const{size:t=50,radius:s="50%",bgColor:o="#4f46e5",textColor:u="#ffffff",fontFamily:c="inherit",fontSize:f,fontWeight:p=600,lineHeight:g,letterSpacing:m=0}=a,h=l(n,r),y=f??t*.4;return i.jsx("div",{style:{width:t,height:t,borderRadius:s,backgroundColor:o,color:u,display:"flex",alignItems:"center",justifyContent:"center",fontFamily:c,fontSize:y,fontWeight:p,lineHeight:g??`${t}px`,letterSpacing:m,userSelect:"none"},children:h})};e.InitialsAvatar=d,e.getInitials=l,Object.defineProperty(e,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "react-intials-avatar-generator",
+  "version": "1.0.0",
+  "description": "Customizable initials-based avatar component for React applications.",
+  "keywords": ["react", "avatar", "initials", "react-avatar", "profile-avatar"],
+  "author": "Ankit Kumar Pandey",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ankit91153/react-initials-avatar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ankit91153/react-initials-avatar/issues"
+  },
+  "homepage": "https://github.com/Ankit91153/react-initials-avatar#readme",
+  "type": "module",
+  "main": "./dist/react-initials-avatar.umd.js",
+  "module": "./dist/react-initials-avatar.es.js",
+  "types": "./dist/main.d.ts",
+  "files": ["dist/*.js", "dist/*.d.ts"],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^5.1.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.1"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run build:types && vite build",
+    "build:types": "tsc --project tsconfig.build.json",
+    "lint": "eslint .",
+    "prepare": "npm run build"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/react-initials-avatar.es.js",
+      "require": "./dist/react-initials-avatar.umd.js"
+    }
+  }
+}