@tamnguyenduc/ui-components

React Native UI components for building an employee/HR app. Covers the full CRUD surface: list, detail, create, update, delete.

Installation

npm install @tamnguyenduc/ui-components

Peer dependencies

Must already be installed in the consuming app:

react >=19
react-native >=0.81

No other runtime dependencies are required — every component is built on core React Native primitives only (View, Text, Image, TextInput, FlatList, TouchableOpacity, Modal).

Import

import {
  EmployeeAvatar,
  EmployeeCard,
  EmployeeList,
  EmployeeProfileHeader,
  EmployeeForm,
  ConfirmDialog,
  type Employee,
  type EmployeeStatus,
  type EmployeeFormValues,
} from '@tamnguyenduc/ui-components';

Core type

type EmployeeStatus = 'online' | 'offline' | 'away' | 'busy';

interface Employee {
  id: string;
  name: string;
  title?: string;
  department?: string;
  email?: string;
  phone?: string;
  avatarUrl?: string;
  status?: EmployeeStatus;
}

This is the shape every component expects for an "employee". Map your API response to this shape before passing it to a component (or extend it — components only read the fields listed above and ignore extras).

Components

EmployeeAvatar

Circular avatar. Falls back to initials (derived from name) when avatarUrl is not provided. Shows a small presence-status dot when status is set.

| Prop | Type | Default | Description | |---|---|---|---| | name | string | required | Used to render initials when there's no image | | avatarUrl | string | — | Remote image URL | | size | number | 40 | Diameter in pixels | | status | EmployeeStatus | — | Shows a colored badge (online=green, away=amber, busy=red, offline=gray). Omit to hide the badge | | style | StyleProp<ViewStyle> | — | Extra style for the outer container |

<EmployeeAvatar name="Nguyen Duc Tam" avatarUrl={employee.avatarUrl} status="online" size={48} />

EmployeeCard

Compact row: avatar + name + title + department. Use inside a list.

| Prop | Type | Default | Description | |---|---|---|---| | employee | Employee | required | Employee to render | | onPress | (employee: Employee) => void | — | Makes the card pressable (navigates to detail, typically). Card renders as static View when omitted | | style | StyleProp<ViewStyle> | — | Extra style for the card |

<EmployeeCard employee={employee} onPress={(e) => navigation.navigate('EmployeeDetail', { id: e.id })} />

EmployeeList — serves the List endpoint

FlatList of EmployeeCard.

| Prop | Type | Default | Description | |---|---|---|---| | employees | Employee[] | required | Data to render | | onEmployeePress | (employee: Employee) => void | — | Forwarded to each EmployeeCard | | emptyMessage | string | 'No employees found' | Shown when employees is empty | | style | StyleProp<ViewStyle> | — | Extra style for the outer container |

function EmployeeListScreen() {
  const [employees, setEmployees] = useState<Employee[]>([]);

  useEffect(() => {
    fetch('/api/employees')
      .then((r) => r.json())
      .then(setEmployees);
  }, []);

  return (
    <EmployeeList
      employees={employees}
      onEmployeePress={(e) => navigation.navigate('EmployeeDetail', { id: e.id })}
    />
  );
}

This component has no built-in search. If you need search/filtering, filter the employees array yourself before passing it in (client-side), or fetch with your own query params (server-side).

EmployeeProfileHeader — serves the Detail and Delete endpoints

Classic side-by-side profile header: avatar on the left, identity and contact info (title, department, email, phone shown as plain text) stacked on the right. No Call/Email buttons — those are not part of this component. An optional Delete action is built in.

| Prop | Type | Default | Description | |---|---|---|---| | employee | Employee | required | Employee to render | | onDelete | (employee: Employee) => void | — | Shows a "Delete" button below the info. Opens a built-in confirmation dialog first; onDelete fires only after the user confirms | | style | StyleProp<ViewStyle> | — | Extra style for the outer container |

function EmployeeDetailScreen({ employeeId }: { employeeId: string }) {
  const [employee, setEmployee] = useState<Employee | null>(null);

  useEffect(() => {
    fetch(`/api/employees/${employeeId}`)
      .then((r) => r.json())
      .then(setEmployee);
  }, [employeeId]);

  if (!employee) return null;

  return (
    <EmployeeProfileHeader
      employee={employee}
      onDelete={async (e) => {
        await fetch(`/api/employees/${e.id}`, { method: 'DELETE' });
        navigation.goBack();
      }}
    />
  );
}

EmployeeForm — serves the Create and Update endpoints

Single form reused for both create and update. Validates name (required) and email (format) before calling onSubmit; invalid submissions are blocked and show inline field errors instead.

| Prop | Type | Default | Description | |---|---|---|---| | initialValues | Partial<EmployeeFormValues> | — | Omit for create; pass the existing employee for update (prefills fields) | | onSubmit | (values: EmployeeFormValues) => void | required | Called with validated form values | | onCancel | () => void | — | Shows a "Cancel" button when provided | | submitLabel | string | 'Save' | Text on the submit button (e.g. 'Create employee' vs 'Save changes') | | style | StyleProp<ViewStyle> | — | Extra style for the outer container |

interface EmployeeFormValues {
  name: string;
  title?: string;
  department?: string;
  email?: string;
  phone?: string;
  avatarUrl?: string;
}

Create:

<EmployeeForm
  submitLabel="Create employee"
  onCancel={() => navigation.goBack()}
  onSubmit={async (values) => {
    await fetch('/api/employees', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(values),
    });
    navigation.goBack();
  }}
/>

Update:

<EmployeeForm
  initialValues={employee} // Employee is assignable to Partial<EmployeeFormValues>
  submitLabel="Save changes"
  onCancel={() => navigation.goBack()}
  onSubmit={async (values) => {
    await fetch(`/api/employees/${employee.id}`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(values),
    });
    navigation.goBack();
  }}
/>

EmployeeForm does not include an image picker — avatarUrl is a plain text field for a hosted image URL. If you need on-device image upload, upload the file yourself and pass the resulting URL into initialValues.avatarUrl / read it back from values.avatarUrl in onSubmit.

ConfirmDialog

Generic modal confirmation dialog. EmployeeProfileHeader already uses this internally for its Delete action — use this directly if you need a confirmation elsewhere (e.g. confirming a bulk action).

| Prop | Type | Default | Description | |---|---|---|---| | visible | boolean | required | Controls dialog visibility | | title | string | required | Dialog title | | message | string | — | Supporting body text | | confirmLabel | string | 'Confirm' | Confirm button text | | cancelLabel | string | 'Cancel' | Cancel button text | | destructive | boolean | false | Styles the confirm button red | | onConfirm | () => void | required | Called when confirmed | | onCancel | () => void | required | Called when cancelled or dismissed |

<ConfirmDialog
  visible={showDialog}
  title="Discard changes?"
  message="Unsaved edits will be lost."
  confirmLabel="Discard"
  destructive
  onConfirm={() => { setShowDialog(false); navigation.goBack(); }}
  onCancel={() => setShowDialog(false)}
/>

CRUD → component map

| Endpoint | Component(s) | |---|---| | GET /employees (list) | EmployeeList | | GET /employees/:id (detail) | EmployeeProfileHeader | | POST /employees (create) | EmployeeForm (no initialValues) | | PATCH /employees/:id (update) | EmployeeForm (initialValues={employee}) | | DELETE /employees/:id (delete) | EmployeeProfileHeader's onDelete prop (confirmation built in via ConfirmDialog) |

None of the components perform network requests themselves — they only call the callback props (onSubmit, onDelete, onEmployeePress, ...) with the relevant data. Wiring those callbacks to your actual API calls (as shown in the examples above) is the integrating app's responsibility.

Development (this repo only)

This repo doubles as the demo app (Expo + Storybook) used to build/preview the components in src/.

npm run storybook:ios      # or storybook:android
npm run build               # compile src/ -> dist/ for publishing

Publishing new versions

npm version patch   # or minor / major
npm publish

prepublishOnly runs the build automatically; only dist/, package.json, LICENSE and this README.md are included in the published tarball (see files in package.json).