Skip to main content
useOne is a modified version of TanStack Query’s useQuery for retrieving a single record from a resource. It uses the getOne method from the dataProvider.

​
Usage

import { useOne } from "@refinedev/core";

interface IProduct {
  id: number;
  name: string;
  price: number;
}

const product = useOne<IProduct>({
  resource: "products",
  id: 123,
});

​
Parameters

​
resource
string
Resource name for API data interactions. If not provided, it will be inferred from the route.
​
id
BaseKey
required
ID of the record to fetch. Can be a string or number.
​
meta
MetaQuery
Meta data for the dataProvider. Can be used to pass additional parameters to data provider methods.
​
dataProviderName
string
default:"default"
If there is more than one dataProvider, you should specify which one to use.
​
queryOptions
UseQueryOptions
TanStack Query’s useQuery options.
​
successNotification
OpenNotificationParams | false | ((data, params) => OpenNotificationParams | false)
Success notification configuration. Set to false to disable.
​
errorNotification
OpenNotificationParams | false | ((error, params) => OpenNotificationParams | false)
Error notification configuration. Set to false to disable.
​
liveMode
'auto' | 'manual' | 'off'
Live/Realtime mode configuration.
​
onLiveEvent
(event) => void
Callback to handle live events.
​
liveParams
object
Additional parameters for live queries.
​
overtimeOptions
UseLoadingOvertimeOptionsProps
Configuration for loading overtime behavior.

​
Return Values

​
result
TData | undefined
The fetched record data.
​
query
QueryObserverResult
TanStack Query’s useQuery return object.
​
overtime
object
Loading overtime information.

​
Examples

​
Basic Usage

import { useOne } from "@refinedev/core";

const { result, query } = useOne({
  resource: "products",
  id: 123,
});

const product = result; // { id: 123, name: "Product", ... }

​
Conditional Fetching

const [productId, setProductId] = useState<number>();

const { result } = useOne({
  resource: "products",
  id: productId,
  queryOptions: {
    enabled: !!productId, // Only fetch when productId is defined
  },
});

​
With Meta Data

const { result } = useOne({
  resource: "products",
  id: 123,
  meta: {
    fields: ["id", "name", "price", "category"],
  },
});

​
With Data Transformation

const { result } = useOne({
  resource: "products",
  id: 123,
  queryOptions: {
    select: (data) => ({
      ...data,
      data: {
        ...data.data,
        displayName: `${data.data.name} - $${data.data.price}`,
      },
    }),
  },
});

​
With Multiple Data Providers

const { result } = useOne({
  resource: "products",
  id: 123,
  dataProviderName: "apiV2",
});

​
Handling Loading and Error States

const { result, query } = useOne({
  resource: "products",
  id: 123,
});

if (query.isLoading) {
  return <div>Loading...</div>;
}

if (query.isError) {
  return <div>Error: {query.error.message}</div>;
}

return (
  <div>
    <h1>{result?.name}</h1>
    <p>${result?.price}</p>
  </div>
);

​
Manual Refetch

const { result, query } = useOne({
  resource: "products",
  id: 123,
});

const handleRefresh = () => {
  query.refetch();
};

return (
  <div>
    <button onClick={handleRefresh}>Refresh</button>
    <pre>{JSON.stringify(result, null, 2)}</pre>
  </div>
);

​
Type Parameters

  • TQueryFnData - Result data type returned by the query function. Extends BaseRecord.
  • TError - Custom error type that extends HttpError.
  • TData - Result data type returned by the select function. Extends BaseRecord. Defaults to TQueryFnData.

​
FAQ

Use the queryOptions.enabled parameter:
const { result } = useOne({
  resource: "posts",
  id: 123,
  queryOptions: {
    enabled: false,
  },
});
The query will be automatically disabled until id is defined. This prevents unnecessary API calls.
Yes, you can explicitly provide the resource parameter:
const { result } = useOne({
  resource: "products",
  id: 123,
});

Build docs developers (and LLMs) love

Get started for freeTalk to us