React

@raster-app/react includes RasterPicker, a complete asset picker. To build your own UI, use RasterProvider and the hooks.

RasterPicker

RasterPicker handles sign-in, browsing, search, upload, and picking in one component. Your app receives the picked asset in onPick. Render it inside a RasterProvider and import @raster-app/react/styles.css.

See the quick start for code and props.

RasterProvider

RasterProvider takes a client, or a config to create one:

The provider reads these props once, on mount. To change them, remount it with a new key.

Build your own UI

Use the hooks inside a RasterProvider:

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>
    </>
  )
}

Hooks

Call hooks inside a RasterProvider. Errors are RasterApiErrors; show them with toUserMessage(error) (see Errors).

useSession()

It re-renders when the credential changes. Show sign-in once credentials is defined and isConfigured is false.

useSignIn(options?)

options takes scope and organizationId, as auth.signInWithDevice does.

state.status is one of:

• idle: nothing running. Also the state after success (useSession has the new credential) or cancel.
• connecting: the sign-in or key check is running.
• awaitingApproval: show state.device.userCode. The consent page is state.device.verificationUrl.
• error: failed with state.error.

useOrganizations() and useLibraries(options)

useOrganizations() returns data ({ id, name, libraryCount } each), isLoading, and error.

useLibraries({ organizationId, organizationName? }) returns every library in data, with isLoading and error. Each library has organizationId, organizationName, and access ('write', 'read', or null). Pass organizationId: null until an organization is chosen.

useAssets(options)

useAssets({ organizationId, libraryId }) lists a library's assets a page at a time. Pass libraryId: null until a library is open.

useAssetSearch(scope, query)

scope is { organizationId, libraryId }; libraryId: null searches the whole organization, and a null scope turns search off. Pass the search box's text as query. The hook searches once typing pauses and keeps the previous results until new ones arrive.

useAssetUpload()

function UploadInput() {
  const { upload, state } = useAssetUpload()

  return (
    <input
      type="file"
      disabled={state.status === 'uploading' || state.status === 'processing'}
      onChange={(event) => {
        const file = event.target.files?.[0]
        if (file) void upload({ organizationId: 'acme', libraryId: 'lib-1', source: file })
      }}
    />
  )
}

upload(options) takes the assets.upload options except signal. It resolves with the processed Asset (for a variant, its parent), or null if the upload failed, was cancelled, or was still processing. state tells you which.

state.status is one of:

• idle: no upload running.
• uploading: the file is uploading.
• processing: Raster is processing the file. state.asset is the uploaded asset.
• done: state.asset is the processed asset.
• timed-out: still processing when the wait ended. state.asset is the uploaded asset.
• error: failed with state.error.

cancel() stops the upload; reset() returns state to idle. Other hooks' libraries, assets, and search results update once an upload settles.

usePromoteVariant()

function SetAsDefault({ assetId, variantId }: { assetId: string; variantId: string }) {
  const { promote, state } = usePromoteVariant()

  return (
    <button
      type="button"
      disabled={state.status === 'promoting'}
      onClick={() =>
        void promote({ organizationId: 'acme', libraryId: 'lib-1', assetId, variantId })
      }
    >
      Set as default
    </button>
  )
}

promote(options) makes the variant the default and resolves with the updated asset, or null if it failed or hadn't landed when the wait ended.

To update useAssets results right away, pass optimistic: a function that returns the asset as it should look. useAssets shows it until the promote lands or fails.

state.status is idle, promoting, done (with state.asset), timed-out, or error (with state.error). reset() returns it to idle.

useRasterNavigation(options)

useRasterNavigation({ organizations }) tracks the organization, open library, open asset, and search text. Pass organizations from useOrganizations(), or null while loading. It selects the remembered organization if still reachable, otherwise the first.

It saves the organization and library in the provider's state store. A StateStore has three async methods: get(key), set(key, value), and delete(key).