@raster-app/react

Raster's asset picker for React, and hooks to build your own Raster UI.

Documentation

raster.app/docs/api/sdk

Requirements

• React 18 or 19
• Node.js 22.12 or later

Installation

npm install @raster-app/react

It includes @raster-app/sdk and re-exports all of it, so import the client, toUserMessage and types such as Asset from @raster-app/react.

Usage

Add the picker

import {
	RasterPicker,
	RasterProvider,
	getFullSizeUrl,
	localStorageCredentialStore,
} from '@raster-app/react'
import '@raster-app/react/styles.css'

export function Picker({ onImage }: { onImage: (url: string) => void }) {
	return (
		<RasterProvider
			config={{
				host: { name: 'My App', openExternal: (url) => window.open(url, '_blank') },
				credentials: localStorageCredentialStore(),
			}}
		>
			<RasterPicker onPick={(asset) => onImage(getFullSizeUrl(asset) ?? '')} />
		</RasterProvider>
	)
}

host.name is the name Raster's sign-in page shows for your app, and openExternal opens that page in the user's browser. credentials is where the sign-in is kept.

The picker signs the user in, browses their organizations and libraries, searches, uploads, and lets them pick an asset or one of its versions. It fills its container.

| Prop | What it does | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | onPick(asset, organizationId) | Called with the picked asset. getFullSizeUrl(asset) is its image. Leave it out for a picker that only browses. | | organizationId | Limits sign-in to this organization. | | scope | 'org' to ask for one organization, 'user' for the whole account. Defaults to 'org' with an organizationId. | | onError(error) | Called with each error the picker shows, for logging. | | theme | 'light' or 'dark'. Follows the system when unset. |

Build your own UI

The same provider gives your components hooks.

import {
	RasterProvider,
	createRasterClient,
	getThumbUrl,
	localStorageCredentialStore,
	useAssets,
	useSession,
	useSignIn,
} from '@raster-app/react'

// Create the client once, outside any component.
const client = createRasterClient({
	host: { name: 'My App', openExternal: (url) => window.open(url, '_blank') },
	credentials: localStorageCredentialStore(),
})

export function App() {
	return (
		<RasterProvider client={client}>
			<Library />
		</RasterProvider>
	)
}

function Library() {
	const { credentials, isConfigured, signOut } = useSession()
	const { state, signInWithDevice } = useSignIn()
	// Your organization's and library's ids.
	const { assets, hasMore, loadMore } = useAssets({ organizationId: 'acme', libraryId: 'lib-1' })

	if (credentials === undefined) return null // still reading the saved sign-in

	if (!isConfigured) {
		if (state.status === 'awaitingApproval') {
			return <p>Approve {state.device.userCode} in the Raster tab that just opened.</p>
		}
		return (
			<button type="button" onClick={signInWithDevice}>
				Sign in with Raster
			</button>
		)
	}

	return (
		<>
			{assets?.map((asset) => (
				<img key={asset.id} src={getThumbUrl(asset)} alt={asset.name ?? ''} width={200} />
			))}
			{hasMore && (
				<button type="button" onClick={loadMore}>
					Load more
				</button>
			)}
			<button type="button" onClick={signOut}>
				Sign out
			</button>
		</>
	)
}

| Hook | What it gives you | | ------------------------------------------ | ---------------------------------------------------------------------- | | useSession() | isConfigured, isSignedIn, userName and signOut(). | | useSignIn() | Sign-in with Raster's device flow or an API key. | | useOrganizations() | The organizations the user can reach, in data. | | useLibraries({ organizationId }) | An organization's libraries, in data, each with the user's access. | | useAssets({ organizationId, libraryId }) | A library's assets, with loadMore(). | | useAssetSearch(scope, query) | Search results, hits and found, as the user types. | | useAssetUpload() | upload() a file, then wait for Raster to process it. | | usePromoteVariant() | Make a variant its asset's default. | | useRasterNavigation({ organizations }) | The open organization, library and asset, remembered between visits. |

RasterProvider takes a client, or a config to create one, and state, where navigation is remembered: memoryStateStore() by default, or localStorageStateStore().

Errors

Every failure is a RasterApiError. Show the user toUserMessage(error), and branch on error.code.

License

MIT