API Reference

$3

$3

For custom implementations and advanced use cases.

#### Parameters

if (error) {
return

if (dismissedAt) {
return (

return (

Usage Examples

$3

$3

For secure environments, configure JWT authentication:

$3

$3

const CustomError = ({ error }) => (

function AdvancedBanner() {
return (
itemId="advanced-banner"
LoadingComponent={CustomLoader}
ErrorComponent={CustomError}
>

$3

$3

$3

Use the restore function to bring back previously dismissed content:

`tsx
import { useDismissibleItem } from '@dismissible/react-client';

function RestorableBanner({ itemId }) {
const { dismissedAt, dismiss, restore, isLoading } = useDismissibleItem(itemId);

if (dismissedAt) {
return (


Under the hood, Dismissible uses a BatchScheduler that implements DataLoader-style request coalescing:

1. Request Collection: When multiple components or useDismissibleItem hooks mount during the same render cycle, each request is queued rather than fired immediately.

2. Microtask Scheduling: The scheduler uses queueMicrotask() to defer execution until after all synchronous code in the current JavaScript tick completes.

3. Batch Execution: All queued requests are combined into a single batch API call (up to 50 items per batch, with automatic splitting for larger sets).

4. Result Distribution: When the API responds, results are distributed back to each waiting component.

`
┌─────────────────────────────────────────────────────────────────┐
│ Same JavaScript Tick │
├─────────────────────────────────────────────────────────────────┤
│ Component A Component B Component C │
│ requests "banner" requests "modal" requests "tooltip" │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ ▼ │
│ ┌───────────────┐ │
│ │ BatchScheduler│ │
│ │ Queue │ │
│ └───────┬───────┘ │
│ │ │
│ queueMicrotask │
└────────────────────────────┼────────────────────────────────────┘
▼
┌─────────────────────────┐
│ Single API Call │
│ POST /v1/users/{id}/ │
│ items/batch │
│ ["banner", "modal", │
│ "tooltip"] │
└─────────────────────────┘
`

#### Example: Dashboard with Multiple Dismissibles

`tsx
// Without batching: 5 separate API calls
// With batching: 1 single API call containing all 5 item IDs

function Dashboard() {
return (


The BatchScheduler includes several optimizations:

- Request Deduplication: If the same itemId is requested multiple times in the same tick, only one request is made and the result is shared.
- In-Memory Caching: Previously fetched items are cached in memory to avoid redundant API calls.
- Cache Priming: Items loaded from localStorage are automatically primed in the batch cache.
- Cache Sync: When items are dismissed or restored, the batch cache is updated to ensure consistency.

#### Using the Hook with Batching

The batching is completely transparent when using the useDismissibleItem hook:

`tsx
function NotificationCenter() {
// All three hooks will batch their requests into a single API call
const notification1 = useDismissibleItem('notification-1');
const notification2 = useDismissibleItem('notification-2');
const notification3 = useDismissibleItem('notification-3');

// Rendering logic...
}
`

#### Performance Impact

| Scenario | Without Batching | With Batching |
|----------|------------------|---------------|
| 5 dismissible items | 5 HTTP requests | 1 HTTP request |
| 20 dismissible items | 20 HTTP requests | 1 HTTP request |
| 100 dismissible items | 100 HTTP requests | 2 HTTP requests* |

\ Batches are automatically split at 50 items to respect API limits*

$3

By default, Dismissible uses a built-in HTTP client powered by openapi-fetch. However, you can provide your own HTTP client implementation by passing a client prop to the DismissibleProvider. This is useful when you need:

- Custom headers (correlation IDs, tracing, etc.)
- Request/response interceptors
- Use a different HTTP library (axios, ky, etc.)
- Analytics and logging
- Custom error handling

#### The DismissibleClient Interface

Your custom client must implement the DismissibleClient interface:

`typescript
import type { DismissibleClient, DismissibleItem } from '@dismissible/react-client';

interface DismissibleClient {
getOrCreate: (params: {
userId: string;
itemId: string;
baseUrl: string;
authHeaders: { Authorization?: string };
signal?: AbortSignal;
}) => Promise;

// Required for automatic batching - fetches multiple items in one API call
batchGetOrCreate: (params: {
userId: string;
itemIds: string[]; // Array of item IDs (max 50)
baseUrl: string;
authHeaders: { Authorization?: string };
signal?: AbortSignal;
}) => Promise;

dismiss: (params: {
userId: string;
itemId: string;
baseUrl: string;
authHeaders: { Authorization?: string };
}) => Promise;

restore: (params: {
userId: string;
itemId: string;
baseUrl: string;
authHeaders: { Authorization?: string };
}) => Promise;
}
`

> Note: The batchGetOrCreate method is essential for the automatic request batching feature. When multiple components request items in the same render cycle, this method is called instead of multiple getOrCreate calls.

#### Example: Custom Client with Axios

`tsx
import axios from 'axios';
import { v4 as uuid } from 'uuid';
import { DismissibleProvider } from '@dismissible/react-client';
import type { DismissibleClient } from '@dismissible/react-client';

const axiosClient: DismissibleClient = {
getOrCreate: async ({ userId, itemId, baseUrl, authHeaders, signal }) => {
const response = await axios.get(
${baseUrl}/v1/users/${userId}/items/${itemId},
{
headers: {
...authHeaders,
'X-Correlation-ID': uuid(),
},
signal,
}
);
return response.data.data;
},

// Batch endpoint for automatic request coalescing
batchGetOrCreate: async ({ userId, itemIds, baseUrl, authHeaders, signal }) => {
const response = await axios.post(
${baseUrl}/v1/users/${userId}/items/batch,
{ itemIds },
{
headers: {
...authHeaders,
'X-Correlation-ID': uuid(),
},
signal,
}
);
return response.data.data;
},

dismiss: async ({ userId, itemId, baseUrl, authHeaders }) => {
const response = await axios.delete(
${baseUrl}/v1/users/${userId}/items/${itemId},
{
headers: {
...authHeaders,
'X-Correlation-ID': uuid(),
},
}
);
return response.data.data;
},

restore: async ({ userId, itemId, baseUrl, authHeaders }) => {
const response = await axios.post(
${baseUrl}/v1/users/${userId}/items/${itemId},
{},
{
headers: {
...authHeaders,
'X-Correlation-ID': uuid(),
},
}
);
return response.data.data;
},
};

function App() {
return (
userId="user-123"
baseUrl="https://api.yourapp.com"
client={axiosClient}
>


);
}
`

#### Example: Custom Client with Logging

`tsx
import type { DismissibleClient } from '@dismissible/react-client';

const loggingClient: DismissibleClient = {
getOrCreate: async ({ userId, itemId, baseUrl, authHeaders, signal }) => {
console.log([Dismissible] Fetching item: ${itemId} for user: ${userId});
const startTime = performance.now();

const response = await fetch(
${baseUrl}/v1/users/${userId}/items/${itemId},
{
method: 'GET',
headers: authHeaders,
signal,
}
);

const data = await response.json();
console.log([Dismissible] Fetched in ${performance.now() - startTime}ms);

if (!response.ok) {
throw new Error(data.message || 'Failed to fetch dismissible item');
}

return data.data;
},

batchGetOrCreate: async ({ userId, itemIds, baseUrl, authHeaders, signal }) => {
console.log([Dismissible] Batch fetching ${itemIds.length} items for user: ${userId});
const startTime = performance.now();

const response = await fetch(
${baseUrl}/v1/users/${userId}/items/batch,
{
method: 'POST',
headers: {
...authHeaders,
'Content-Type': 'application/json',
},
body: JSON.stringify({ itemIds }),
signal,
}
);

const data = await response.json();
console.log([Dismissible] Batch fetched ${itemIds.length} items in ${performance.now() - startTime}ms);

if (!response.ok) {
throw new Error(data.message || 'Failed to batch fetch dismissible items');
}

return data.data;
},

dismiss: async ({ userId, itemId, baseUrl, authHeaders }) => {
console.log([Dismissible] Dismissing item: ${itemId});

const response = await fetch(
${baseUrl}/v1/users/${userId}/items/${itemId},
{
method: 'DELETE',
headers: authHeaders,
}
);

const data = await response.json();

if (!response.ok) {
throw new Error(data.message || 'Failed to dismiss item');
}

console.log([Dismissible] Item dismissed at: ${data.data.dismissedAt});
return data.data;
},

restore: async ({ userId, itemId, baseUrl, authHeaders }) => {
console.log([Dismissible] Restoring item: ${itemId});

const response = await fetch(
${baseUrl}/v1/users/${userId}/items/${itemId},
{
method: 'POST',
headers: authHeaders,
}
);

const data = await response.json();

if (!response.ok) {
throw new Error(data.message || 'Failed to restore item');
}

console.log([Dismissible] Item restored successfully);
return data.data;
},
};

function App() {
return (
userId="user-123"
baseUrl="https://api.yourapp.com"
client={loggingClient}
>


);
}
`

#### Example: Custom Client with Retry Logic

`tsx
import type { DismissibleClient } from '@dismissible/react-client';

async function fetchWithRetry(
url: string,
options: RequestInit,
retries = 3
): Promise {
for (let attempt = 1; attempt <= retries; attempt++) {
try {
const response = await fetch(url, options);
if (response.ok || attempt === retries) {
return response;
}
} catch (error) {
if (attempt === retries) throw error;
}
// Exponential backoff
await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 100));
}
throw new Error('Max retries reached');
}

const retryClient: DismissibleClient = {
getOrCreate: async ({ userId, itemId, baseUrl, authHeaders, signal }) => {
const response = await fetchWithRetry(
${baseUrl}/v1/users/${userId}/items/${itemId},
{ method: 'GET', headers: authHeaders, signal }
);
const data = await response.json();
return data.data;
},

batchGetOrCreate: async ({ userId, itemIds, baseUrl, authHeaders, signal }) => {
const response = await fetchWithRetry(
${baseUrl}/v1/users/${userId}/items/batch,
{
method: 'POST',
headers: { ...authHeaders, 'Content-Type': 'application/json' },
body: JSON.stringify({ itemIds }),
signal,
}
);
const data = await response.json();
return data.data;
},

dismiss: async ({ userId, itemId, baseUrl, authHeaders }) => {
const response = await fetchWithRetry(
${baseUrl}/v1/users/${userId}/items/${itemId},
{ method: 'DELETE', headers: authHeaders }
);
const data = await response.json();
return data.data;
},

restore: async ({ userId, itemId, baseUrl, authHeaders }) => {
const response = await fetchWithRetry(
${baseUrl}/v1/users/${userId}/items/${itemId},
{ method: 'POST', headers: authHeaders }
);
const data = await response.json();
return data.data;
},
};
`

Styling

The library includes minimal default styles. You can override them or provide your own:

`css
/ Default classes you can style /
.dismissible-container {
/ Container for the dismissible content /
}

.dismissible-loading {
/ Loading state /
}

.dismissible-error {
/ Error state /
}

.dismissible-button {
/ Default dismiss button /
}
`

Self-Hosting

Dismissible is designed to be self-hosted. You have full control over your data.

$3

The fastest way to get started:

`bash
docker run -p 3001:3001 dismissibleio/dismissible-api:latest
`

See the Docker documentation for production configuration.

$3

Integrate directly into your existing NestJS application:

`bash
npm install @dismissible/nestjs-api
``

See the NestJS documentation for setup instructions.

Support

- Documentation
- GitHub - React Client
- GitHub - API Server

License

MIT © Dismissible

Changelog

See CHANGELOG.md for a detailed list of changes.