🧠 LensProvider

The LensProvider is the foundational context component in @locospec/lens-react. It wraps your entire Lens-powered UI, fetches view configuration, and provides global context to all Lens components like Datatable, SimpleFilters, View, and more.

It also internally uses React Query for data fetching and caching, and supports developer tools via ReactQueryDevtools.

✅ Responsibilities

Fetches view configuration from a backend endpoint or a local configCallback.
Makes view configuration, permissions, and contextual data available to child components.
Handles loading and error states gracefully.
Provides a React context via LensContext.
Wraps all child components with a QueryClientProvider.

📦 Import

import { LensProvider } from "@locospec/lens-react";

🔧 Props

⚙️ `lensConfiguration` (required)

An object that defines how to fetch configuration and what contextual data to pass along. This can include:

Prop	Type	Description
`endpoint`	`string`	API base path to fetch config, records, and dropdown options.
`permissionHeaders`	`Record<string, string>`	Headers (e.g., CSRF token) for secure API requests.
`configCallback`	`() => Promise<Config>`	Optional local callback to return configuration without API call.
`dataCallback`	`() => Promise<Data>`	Optional callback to override default data fetching from API.
`context`	`Record<string, any>`	Custom data to pass to components downstream.
`view`	`string`	Name of the specific view (can be used to scope filters, queries, etc).

⚙️ `showDevTools`

boolean
If set to true, the React Query Devtools will be displayed to help with debugging data fetches.

🧪 Example

const lensConfig = {
  endpoint: "/api/data/my-table",
  permissionHeaders: {
    'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content,
  },
  configCallback: () => fetchSomeCustomConfig(),
  dataCallback: () => fetchCustomData(),
};
 
<LensProvider lensConfiguration={lensConfig} showDevTools={true}>
  <View>
    <Datatable />
  </View>
</LensProvider>

🚦 Loader & Error Handling

A full-screen loader is shown while configuration is being fetched.
On failure, the provider renders a simple error fallback.
Once config is available, it passes it down through the LensContext.

💡 Pro Tip

You can access context values (like configuration, loading state, etc.) via custom hooks or LensContext.Consumer:

import { useContext } from "react";
import { LensContext } from "@locospec/lens-react";
 
const ctx = useContext(LensContext);
console.log(ctx?.config);

Lens Provider