API Reference

Everything you need to add delightful loading messages to your app.

Quick Start

Get a random loading message with a single request. No API key required.

GET https://flibbertigibbeting.dev/api/message

{
  "message": "Reticulating splines...",
  "category": "systems",
  "tags": ["classic", "nostalgic"],
  "tone": "whimsical",
  "safe": true
}

Base URL

https://flibbertigibbeting.dev/api

All endpoints are relative to this base URL.

Endpoints

GET/message

Returns a random loading message. Optionally filter by category or tone.

Query Parameters

Parameter	Type	Description
category	string	Filter by category (e.g., "whimsical", "tech", "existential", "agentic")
tone	string	Filter by tone (e.g., "cheeky", "dry", "nerdy")
safe	boolean	Set to false to include edgy messages (default: true)

Example

GET /message?category=tech&tone=nerdy

GET/daily

Returns a consistent message that changes daily. Great for "phrase of the day" features.

Response

{
  "message": "Teaching robots to love...",
  "date": "2024-01-15",
  "category": "existential",
  "tone": "dry"
}

Tones

whimsical

Light & airy

cheeky

Playfully bold

dry

Deadpan humor

nerdy

Reference-heavy

Safe Mode

By default, all responses are safe for work and family-friendly. To include edgier content, explicitly set safe=false.

GET /message?safe=false

Note: Edgy messages are still tasteful - think "mildly spicy" not "offensive".

Rate Limits

The API is free and has generous rate limits:

100 requests per minute per IP address
No authentication required
No usage caps for reasonable use

If you need higher limits for a production app, reach out and we'll work something out.

Response Format

All responses are JSON with the following structure:

Field	Type	Description
message	string	The loading message text
category	string	Message category
tags	string[]	Associated tags
tone	string	Message tone/style
safe	boolean	Whether the message is SFW

React Component

Drop-in component for delightful loading states in React apps.

Installation

Install via npm, yarn, or pnpm:

$ npm install @flibbertigibbeting/loading-message

$ yarn add @flibbertigibbeting/loading-message

$ pnpm add @flibbertigibbeting/loading-message

Basic Usage

Import and use the component with zero configuration:

import { LoadingMessage } from '@flibbertigibbeting/loading-message'

function MyComponent() {
  const [isLoading, setIsLoading] = useState(true)

  if (isLoading) {
    return <LoadingMessage />
  }

  return <div>Content loaded!</div>
}

Props

Prop	Type	Default	Description
category	string	-	Filter messages by category
tone	string	-	Filter messages by tone
safe	boolean	true	Only show SFW messages
interval	number	3000	Time between message changes (ms)
showSpinner	boolean	true	Show animated spinner
className	string	-	Custom CSS classes
onMessageChange	function	-	Callback when message updates

Examples

Filtered by Category

<LoadingMessage 
  category="tech" 
  tone="nerdy"
/>

Custom Refresh Interval

<LoadingMessage 
  interval={5000}  // Change every 5 seconds
  showSpinner={false}
/>

With Message Callback

<LoadingMessage 
  onMessageChange={(msg) => {
    console.log('New message:', msg.message)
    analytics.track('loading_message_shown', {
      category: msg.category
    })
  }}
/>

Custom Styling

<LoadingMessage 
  className="text-2xl font-bold text-purple-500"
/>

Hooks

Need more control? Use the hook directly:

import { useLoadingMessage } from '@flibbertigibbeting/loading-message'

function CustomLoader() {
  const { message, isLoading, refresh } = useLoadingMessage({
    category: 'existential',
    interval: 4000
  })

  return (
    <div className="flex flex-col items-center gap-4">
      <p>{message?.message}</p>
      <button onClick={refresh}>
        Get another
      </button>
    </div>
  )
}

Hook Return Values

Value	Type	Description
message	Message \| null	Current message object
isLoading	boolean	True while fetching
error	Error \| null	Error if fetch failed
refresh	function	Manually fetch new message

TypeScript

Full TypeScript support included. Import types as needed:

import type { 
  Message, 
  LoadingMessageProps,
  UseLoadingMessageOptions 
} from '@flibbertigibbeting/loading-message'

// Message type
interface Message {
  message: string
  category: string
  tags: string[]
  tone: string
  safe: boolean
}