OrganizePhotos

Local-first photo organization for React: browse, search, tag, inspect, and export a photo library without uploading the library to a service.

Live demo · Changelog · Library architecture

Why OrganizePhotos

Photo libraries become difficult to use long before they become difficult to store. OrganizePhotos keeps the working library on the device and gives it a workspace built around how people actually look for images: by folder, tag, name, date, and visual context.

It is distributed as both an npm package and installable shadcn source, so you can embed the complete workspace in an existing React application or inspect and adapt the source directly.

What you get

• Local by default — browser libraries use IndexedDB; directory libraries work against a folder the user explicitly selects through the File System Access API.
• Useful ways to find images — search by name, folder, or tag; sort by metadata; and switch between grid, list, masonry, adaptive, and day-level timeline layouts.
• Safe organization — create folders and tags, select images in batches, move items to Trash, and restore them before clearing.
• Image-library essentials — preview originals, inspect dimensions and capture dates, read EXIF dates for newly imported images, and export selected images as resized or converted ZIP archives.

Supported imported image formats are BMP, JPEG, PNG, and WebP. The workspace is designed for desktop browsers with a viewport of at least 1024px.

Quick start

Install from npm

npm install organizephotos

Render the workspace inside a host that already provides Tailwind CSS and shadcn CSS variables:

import { LibraryWorkspace } from 'organizephotos';
import 'organizephotos/styles.css';
import { Toaster } from 'sonner';

export function App() {
  return (
    <>
      <LibraryWorkspace locale="en" />
      <Toaster />
    </>
  );
}

LibraryWorkspace uses Sonner for operation feedback. If the host already renders a shadcn Sonner/Toaster, reuse that one instead of adding another.

Add as shadcn source

Initialize a Base UI host and add the workspace registry:

npx shadcn@latest init --base base
npx shadcn@latest add https://raw.githubusercontent.com/meetqy/organizephotos/main/registry/library-workspace.json

The registry writes source into the host's configured @/components, @/lib, and @/hooks aliases. Import the generated workspace and keep the host's shadcn variables stylesheet loaded:

import { LibraryWorkspace } from '@/components/library/workspace/workspace';
import '@/styles.css';

export function App() {
  return <LibraryWorkspace />;
}

Configure the workspace

LibraryWorkspace accepts displayMode (full or preview), locale (en or zh), messages for message overrides, theme, and className.

<LibraryWorkspace
  displayMode="preview"
  locale="zh"
  theme={{ mode: 'dark' }}
  className="theme-brand"
/>

The workspace theme is scoped to the library, including dialogs, popovers, menus, and other portal content. theme.variables accepts standard shadcn CSS variables when a host needs a one-off override.

Changelog

See the full changelog for release notes, timeline updates, and performance improvements.

Local data boundary

OrganizePhotos does not require an account, server, upload endpoint, or cloud storage provider. Browser-library images and metadata stay in the current browser's IndexedDB. Directory mode stores metadata in the browser and keeps the original files and portable library index in the folder selected by the user.

Directory mode depends on browser File System Access support and permission. The project does not claim cross-device sync or remote backup.

Learn more

• Library module guide — module map and ownership boundaries.
• Data architecture — IndexedDB, directory projection, revisions, and recovery.
• Changelog — released changes and performance fixes.
• Registry source — shadcn installation manifest.

License

OrganizePhotos is released under the GNU Affero General Public License v3.0.