SDK
@headlessly/react
React hooks and providers for building headless UIs with Headless.ly data.
The @headlessly/react package provides React hooks and context providers for seamless integration with Headless.ly.
Installation
npm install @headlessly/react @headlessly/dbSetup
Wrap your app with the HeadlesslyProvider:
import { HeadlesslyProvider } from '@headlessly/react'
function App() {
return (
<HeadlesslyProvider
apiKey={process.env.NEXT_PUBLIC_HEADLESSLY_KEY}
app="crm"
>
<YourApp />
</HeadlesslyProvider>
)
}Hooks
useCollection
Query a collection with automatic loading states:
import { useCollection } from '@headlessly/react'
function ContactList() {
const { data, loading, error, refetch } = useCollection('Contact', {
filter: { status: { $eq: 'active' } },
limit: 25,
sort: '-lastEngagement',
})
if (loading) return <Spinner />
if (error) return <Error message={error.message} />
return (
<ul>
{data.map(contact => (
<li key={contact.id}>{contact.name} - {contact.email}</li>
))}
</ul>
)
}useEntity
Fetch a single entity by ID:
import { useEntity } from '@headlessly/react'
function ContactProfile({ id }: { id: string }) {
const { data: contact, loading } = useEntity('Contact', id)
if (loading || !contact) return <Spinner />
return (
<div>
<h1>{contact.name}</h1>
<p>{contact.email}</p>
<span>Stage: {contact.stage}</span>
</div>
)
}useMutation
Create, update, or delete entities:
import { useMutation } from '@headlessly/react'
function CreateContactForm() {
const { mutate, loading, error } = useMutation('Contact', 'create')
const handleSubmit = async (data: ContactData) => {
const result = await mutate(data)
console.log('Created:', result.id)
}
return (
<form onSubmit={handleSubmit}>
{/* form fields */}
<button disabled={loading}>Create Contact</button>
{error && <p className="text-red-500">{error.message}</p>}
</form>
)
}useFeatureFlag
Evaluate feature flags client-side:
import { useFeatureFlag } from '@headlessly/react'
function Dashboard() {
const showNewChart = useFeatureFlag('new-analytics-chart')
return showNewChart ? <NewChart /> : <LegacyChart />
}useAnalytics
Access analytics methods:
import { useAnalytics } from '@headlessly/react'
function PricingPage() {
const { track } = useAnalytics()
return (
<button onClick={() => track('plan_selected', { plan: 'pro' })}>
Select Pro Plan
</button>
)
}