Skip to content
LogoLogo

How to read a referenced entry

This guide shows you how to read the content that a Reference field points at. You need a component that renders a step first. See How to render a step form.

A Reference field holds a pointer, and not the content. The entry travels beside the content of the step, so you resolve the pointer against the content of the client.

1. Resolve a single reference

Pass the raw field value to useReference() in React, or to getReference() in Svelte.

import { useReference, useStepContent, useStoreGlobal } from '@picked/react/hooks'
 
export function ProductCategory() {
  const content = useStepContent()
  const category = useStoreGlobal(useReference(content?.category))
 
  if (!category) return null
 
  return <span>{String(category.data.name ?? '')}</span>
}

In Svelte, pass a store and not a plain value. Content arrives after the component starts. A plain value therefore holds the result at "not set".

2. Resolve a repeatable reference

Use useReferences() or getReferences(). They give a list in field order.

import { useReferences, useStepContent, useStoreGlobal } from '@picked/react/hooks'
 
export function ProductCategories() {
  const content = useStepContent()
  const categories = useStoreGlobal(useReferences(content?.categories))
 
  return (
    <ul>
      {categories.map((category) => (
        <li key={category.id}>{String(category.data.name ?? '')}</li>
      ))}
    </ul>
  )
}

The list holds no empty places, so you need no check for each item.

Handle a target that does not resolve

A single reference gives an empty result when Picked cannot resolve the target. A repeatable reference leaves the item out of the list.

This happens when somebody deleted the target, when the target belongs to another workspace, or when the chain of references is deeper than the limit.

Render something else for the empty case, as the React example above does.