use-vibes

A lightweight library that transforms any DOM element into an AI-powered micro-app.

Installation

pnpm add use-vibes

Basic Usage

import { ImgGen } from 'use-vibes';
import 'use-vibes/style-loader'; // Quick setup for CSS

function MyComponent() {
  // You can use ImgGen without any props - it includes its own form UI
  return <ImgGen />;

  // Or provide a prompt directly (bypasses the form UI completely)
  // return <ImgGen prompt="A futuristic cityscape with flying cars" />;
}

For image manipulation using base64 data:

import { base64ToFile } from 'use-vibes';

// Convert API response to a File object
const imageFile = base64ToFile(imageResponse.data[0].b64_json, 'my-image.png');

Core Features

Interactive Image Generation

Zero-config Implementation: Add AI image generation to any React app without any configuration
```
{
  /* Includes a built-in form UI for prompt entry and image upload */
}
<ImgGen />;
```

One-line Implementation: Directly specify a prompt for immediate generation (bypasses the form UI)

{
  /* Starts generating immediately, no form shown to the user */
}
<ImgGen prompt="A sunset over mountains" />;

Automatic Database Integration: All images are automatically stored in Fireproof database with version history

// Custom database name
<ImgGen prompt="Forest landscape" database="MyCustomDB" />

// Or pass a database instance
<ImgGen prompt="Forest landscape" database={myDbInstance} />

Prompt Management

Prompt Versioning: Tracks the history of different prompts used to generate an image
- Uses a structured prompts object with timestamp-based keys
- Maintains currentPromptKey to reference the active prompt
Prompt Editing: Users can edit prompts directly in the overlay UI
- Double-click the prompt text to edit
- Press Enter to submit and regenerate with new prompt
- App receives updates via onPromptEdit callback
```
<ImgGen
  prompt="Initial prompt"
  onPromptEdit={(id, newPrompt) => {
    console.log(`Document ${id} updated with new prompt: ${newPrompt}`);
  }}
/>
```

Image Control & Manipulation

Image Regeneration: One-click regeneration with the same or edited prompt
- Preserves document history and adds new versions
- Uses a unique generationId to trigger regeneration while maintaining context

Image Quality Control: Set quality levels for output images

<ImgGen prompt="Detailed artwork" options={{ quality: 'high' }} />

Image Editing with Uploads: Process existing images with AI

<ImgGen prompt="Turn this photo into a watercolor painting" images={[myImageFile]} />

Multiple Image Inputs: Combine multiple images in one generation

<ImgGen prompt="Create a collage of these photos" images={[photo1, photo2, photo3]} />

User Interface Components

Interactive Overlay: Toggle-able information and controls overlay
- Shows prompt text (editable)
- Version navigation controls
- Regenerate/refresh button
- Delete button
```
// Disable overlay for a minimal UI
<ImgGen prompt="Clean interface" overlay={false} />
```
Progress Visualization: Shows generation progress with visual indicators
- Progress bar updates in real-time
- Automatic placeholder display during generation

Error Handling UI: Clean error states with informative messages

<ImgGen
  prompt="Test error handling"
  onError={(error) => {
    console.error('Generation failed:', error.message);
  }}
/>

File Management

File Upload Interface: Built-in support for image uploads
- Drag-and-drop capabilities
- File selection dialog
- Preview of uploaded content

Base64 Conversion: Convert between base64 and File objects

import { base64ToFile } from 'use-vibes';

// Convert API response to a File object
const imageFile = base64ToFile(imageResponse.data[0].b64_json, 'my-image.png');

Integration Features

Event Callbacks

Generation Lifecycle Events: Track the complete generation process

<ImgGen
  prompt="Track this generation"
  onComplete={() => console.log('Generation complete!')}
  onError={(error) => console.error('Generation failed:', error)}
  onDelete={(id) => console.log(`Document ${id} deleted`)}
  onDocumentCreated={(id) => console.log(`New document created: ${id}`)}
/>

State Management

Loading States: Component handles all loading states internally
- Initial waiting state
- Generation in progress state
- Upload waiting state
- Display state for completed images
- Error state
Document Identity Tracking: Smart re-mounting based on document changes
- Uses internal mountKey system to ensure clean state transitions
- Detects identity changes through document ID, prompt, or uploaded file documents

UI Customization

Extensive Styling Options: Multiple ways to customize appearance

CSS Variables for global styling

:root {
  --imggen-text-color: #222;
  --imggen-overlay-bg: rgba(245, 245, 245, 0.85);
  --imggen-accent: #0088ff;
  --imggen-border-radius: 4px;
}

Custom classes for component-level styling

<ImgGen
  prompt="Styled component"
  classes={{
    root: 'my-custom-container',
    image: 'rounded-xl shadow-lg',
    overlay: 'bg-slate-800/70 text-white',
    progress: 'h-2 bg-green-500',
  }}
/>

Gallery Integration

Thumbnail Support: Easily create image galleries

<div className="image-grid">
  {imageDocuments.map((doc) => (
    <ImgGen key={doc._id} _id={doc._id} className="thumbnail" />
  ))}
</div>

Document Reuse: Load existing documents by ID
```
<ImgGen _id="existing-document-id" />
```

Implementation Modes

The ImgGen component has several operational modes that it switches between automatically:

Placeholder Mode: Initial state when no prompt or document ID is provided
Upload Waiting Mode: When files are uploaded but waiting for a prompt
Generating Mode: During the image generation process
Display Mode: When showing a generated image with controls
Error Mode: When an error occurs during generation

The component automatically determines which mode to use based on the current state, providing a seamless experience for both developers and end-users.

Advanced Usage

Debug Mode

Enable debug mode to see detailed console logs about component state:

<ImgGen prompt="Debug this" options={{ debug: true }} />

Custom Image Sizing

Control output image dimensions with the size option:

<ImgGen
  prompt="Landscape format"
  options={{ size: '1536x1024' }} // Landscape
/>

<ImgGen
  prompt="Portrait format"
  options={{ size: '1024x1536' }} // Portrait
/>

Advanced Usage

This guide covers the implementation, configuration, and best practices for using the ImgGen component from the use-vibes library.

Installation

pnpm add use-vibes

CSS Setup

The ImgGen component requires CSS styles. You have two options:

Option A: Explicit CSS Link (Recommended for Production)

Add a CSS link tag to your HTML:

<link rel="stylesheet" href="/node_modules/use-vibes/dist/components/ImgGen.css" />

Or for ESM/CDN environments:

<link rel="stylesheet" href="https://esm.sh/use-vibes@latest/dist/components/ImgGen.css" />

Option B: Automatic CSS Loading (Convenient for Prototyping)

Import the style-loader early in your application:

import 'use-vibes/style-loader'; // Auto-loads CSS when imported

This approach is perfect for quick prototypes, but for production sites, Option A gives you better control over CSS loading order and timing.

Basic Usage

Simple Image Generation

Add AI image generation to any React app with minimal code:

import { ImgGen } from 'use-vibes';

function MyComponent() {
  return (
    <div>
      <ImgGen prompt="A sunset over mountains" />
    </div>
  );
}

Configuration Options

Configure image generation with the options prop:

<ImgGen
  prompt="A detailed cityscape"
  options={{
    model: 'gpt-image-1',
    quality: 'high',
    size: '1024x1024',
    debug: false,
  }}
/>

Available Props

Prop	Type	Description
`prompt`	string	Text prompt for image generation (required unless `_id` is provided)
`_id`	string	Document ID to load a specific image instead of generating a new one
`className`	string	CSS class name for the image element
`alt`	string	Alt text for the image (defaults to prompt)
`images`	File[]	Array of images to edit or combine with AI
`options`	object	Configuration options (see table below)
`database`	string \| Database	Database name or instance to use for storing images
`onComplete`	function	Callback when image load completes successfully
`onError`	function	Callback when image load fails, receives the error as parameter
`onDelete`	function	Callback when an image is deleted, receives the document ID
`onPromptEdit`	function	Callback when the prompt is edited, receives document ID and new prompt
`onDocumentCreated`	function	Callback when a new document is created via drop or file picker
`overlay`	boolean	Whether to show overlay controls and info button (default: `true`)
`classes`	object	Custom CSS classes for styling component parts
`debug`	boolean	Enable debug logging

Options Object Properties

Property	Type	Description
`model`	string	Model to use for image generation, defaults to 'gpt-image-1'
`size`	string	Size of the generated image (1024x1024, 1536x1024, 1024x1536, or 'auto')
`quality`	string	Quality of the generated image (high, medium, low, or auto)
`debug`	boolean	Enable debug logging, defaults to false

Advanced Features

Prompt Management

The ImgGen component tracks the history of different prompts used to generate an image:

<ImgGen
  prompt="Initial prompt"
  onPromptEdit={(id, newPrompt) => {
    console.log(`Document ${id} updated with new prompt: ${newPrompt}`);
  }}
/>

Users can edit prompts directly by double-clicking the prompt text in the overlay UI, then pressing Enter to submit and regenerate with the new prompt.

Image Control & Manipulation

Image Regeneration

The component supports one-click regeneration, preserving document history while adding new versions:

// The regeneration happens internally when the user clicks the refresh button
// or when a new prompt is submitted

Image Quality Control

Set quality levels for output images:

<ImgGen prompt="Detailed artwork" options={{ quality: 'high' }} />

Image Editing with Uploads

Process existing images with AI:

<ImgGen prompt="Turn this photo into a watercolor painting" images={[myImageFile]} />

Multiple Image Inputs

Combine multiple images in one generation:

<ImgGen prompt="Create a collage of these photos" images={[photo1, photo2, photo3]} />

Database Integration

All images are automatically stored in a Fireproof database with version history:

// Custom database name
<ImgGen prompt="Forest landscape" database="MyCustomDB" />

// Or pass a database instance
<ImgGen prompt="Forest landscape" database={myDbInstance} />

Event Callbacks

Track the complete generation process with lifecycle events:

<ImgGen
  prompt="Track this generation"
  onComplete={() => console.log('Generation complete!')}
  onError={(error) => console.error('Generation failed:', error)}
  onDelete={(id) => console.log(`Document ${id} deleted`)}
  onDocumentCreated={(id) => console.log(`New document created: ${id}`)}
/>

UI Controls

Toggle the information overlay and controls:

// Disable overlay for a minimal UI
<ImgGen prompt="Clean interface" overlay={false} />

The overlay includes:

Prompt text (editable)
Version navigation controls
Regenerate/refresh button
Delete button

File Management

Base64 Conversion

Convert between base64 and File objects:

import { base64ToFile } from 'use-vibes';

// Convert API response to a File object
const imageFile = base64ToFile(imageResponse.data[0].b64_json, 'my-image.png');

Styling and Customization

CSS Variables

Override the default styles by setting CSS custom properties in your CSS:

/* In your CSS file */
:root {
  --imggen-text-color: #222;
  --imggen-overlay-bg: rgba(245, 245, 245, 0.85);
  --imggen-accent: #0088ff;
  --imggen-border-radius: 4px;
}

/* Dark theme example */
.dark-theme {
  --imggen-text-color: #f0f0f0;
  --imggen-overlay-bg: rgba(25, 25, 25, 0.85);
  --imggen-accent: #66b2ff;
}

Available CSS Variables

Variable	Default	Description
`--imggen-text-color`	`#333`	Main text color
`--imggen-background`	`#333333`	Background color for placeholder
`--imggen-overlay-bg`	`rgba(255, 255, 255, 0.5)`	Overlay panel background
`--imggen-accent`	`#0066cc`	Accent color (progress bar, etc.)
`--imggen-error-text`	`#ff6666`	Error message text color
`--imggen-border-radius`	`8px`	Border radius for containers
`--imggen-button-bg`	`rgba(255, 255, 255, 0.7)`	Button background color
`--imggen-font-size`	`14px`	Default font size

Custom Classes

For more granular control, provide a classes object with custom CSS classes for specific component parts:

<ImgGen
  prompt="Styled component"
  classes={{
    root: 'my-custom-container',
    image: 'rounded-xl shadow-lg',
    overlay: 'bg-slate-800/70 text-white',
    progress: 'h-2 bg-green-500',
    button: 'hover:bg-blue-600',
  }}
/>

Available Class Slots

Class Property	Description
`root`	Main container element
`image`	The image element
`container`	Container for image and controls
`overlay`	Overlay panel with controls
`progress`	Progress indicator
`placeholder`	Placeholder shown during loading
`error`	Error message container
`controls`	Control buttons container
`button`	Individual buttons
`prompt`	Prompt text/input container
`deleteOverlay`	Delete confirmation dialog

Gallery Implementation

Creating an Image Gallery

Easily create image galleries using document IDs:

<div className="image-grid">
  {imageDocuments.map((doc) => (
    <ImgGen key={doc._id} _id={doc._id} className="thumbnail" />
  ))}
</div>

Loading Existing Documents

Load existing documents by ID:

<ImgGen _id="existing-document-id" />

Operation Modes

The ImgGen component has several operational modes that it switches between automatically:

Placeholder Mode: Initial state when no prompt or document ID is provided
Upload Waiting Mode: When files are uploaded but waiting for a prompt
Generating Mode: During the image generation process
Display Mode: When showing a generated image with controls
Error Mode: When an error occurs during generation

Advanced Usage Examples

Debug Mode

Enable debug mode to see detailed console logs about component state:

<ImgGen prompt="Debug this" options={{ debug: true }} />

Custom Image Sizing

Control output image dimensions with the size option:

<ImgGen
  prompt="Landscape format"
  options={{ size: '1536x1024' }} // Landscape
/>

<ImgGen
  prompt="Portrait format"
  options={{ size: '1024x1536' }} // Portrait
/>

Browser Compatibility

This library is compatible with all modern browsers that support React 18+ and ES6 features.

License

MIT+Apache

Name		Name	Last commit message	Last commit date
Latest commit History 255 Commits
.github/workflows		.github/workflows
examples/react-example		examples/react-example
notes		notes
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
LICENSE.md		LICENSE.md
README.md		README.md
allowed_signers		allowed_signers
llms.txt		llms.txt
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

fireproof-storage/use-vibes

Folders and files

Latest commit

History

Repository files navigation

use-vibes

Installation

Basic Usage

Core Features

Interactive Image Generation

Prompt Management

Image Control & Manipulation

User Interface Components

File Management

Integration Features

Event Callbacks

State Management

UI Customization

Gallery Integration

Implementation Modes

Advanced Usage

Debug Mode

Custom Image Sizing

Advanced Usage

Installation

CSS Setup

Option A: Explicit CSS Link (Recommended for Production)

Option B: Automatic CSS Loading (Convenient for Prototyping)

Basic Usage

Simple Image Generation

Configuration Options

Available Props

Options Object Properties

Advanced Features

Prompt Management

Image Control & Manipulation

Image Regeneration

Image Quality Control

Image Editing with Uploads

Multiple Image Inputs

Database Integration

Event Callbacks

UI Controls

File Management

Base64 Conversion

Styling and Customization

CSS Variables

Available CSS Variables

Custom Classes

Available Class Slots

Gallery Implementation

Creating an Image Gallery

Loading Existing Documents

Operation Modes

Advanced Usage Examples

Debug Mode

Custom Image Sizing

Browser Compatibility

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages