This package provides a number of React Hooks that can be used to retrieve data from the Runly HTTP API.

This package is intended to provide a base for you to build your own custom UIs. If you want something more streamlined, checkout our other packages.


Install the package into your project:

npm install @runly/ui


The RunlyProvider allows you to access the Runly API in any nested component or hook. Render a RunlyProvider at the root of your React app so that the Runly API is available everywhere you need it. You will need to pass your API key that all child components will use.

import React from "react";
import { RunlyProvider } from "@runly/ui";

const WrapMyApp = ({ children }) => (
	<RunlyProvider accessToken={myPublicApiKey}>{children}</RunlyProvider>

export default WrapMyApp;


accessToken: string | Promise<string> | () => string | () => Promise<string>

A public API key or a Promise resolving to an API key or a function that returns the API key or the Promise.

url?: string

Optional Runly API URL that all child components will connect to. This defaults to


useRunlyConfig(): Object

This will return the url and the token configured via the RunlyProvider. This is the base URL and access token that you should use to connect to the Runly API.

import { useEffect, useState } from "react";
import { useRunlyConfig } from "@runly/ui";

const MyOrgComponent = ({ org }) => {
	const { url, token } = useRunlyConfig();
	const [results, setResults] = useState({});

	useEffect(() => {
		if (token) {
			fetch(`${url}/${org}/`, {
				method: "GET",
				headers: {
					Authorization: `Bearer ${token}`
			.then(response => response.json())
			.then(data => setResults(data));
	}, [url, token, org]);

	return <pre>{JSON.stringify(results, null, 2)}</pre>;

export default MyOrgComponent;


useFetchOrgAccounts(): FetchResults

This is a thin wrapper around react-fetch-hooks to retrieve organization accounts for the current user.

import React from "react";
import { useFetchOrgAccounts } from "@runly/ui";

const OrgShower = () => {
	const { isFetched, body: orgs } = useFetchOrgAccounts();

	if (!isFetched) {
		return (
			<span>Loading orgs...</span>

	return (
			{{ id, name }) => (
				<li key={id}>{name}</li>

export default OrgShower;


useRequeueRun(org: string, runId: string): FetchResults

This is a thin wrapper around a lazy react-fetch-hook to requeue a failed run.


org: string

The organization that the run to be requeued belongs to. If the org is null or empty, the hook won’t do anything.

runId: string

The ID of the run to requeue. If the runId is null or empty, the hook won’t do anything.

import React, { useCallback } from "react";
import { useRequeueRun } from "@runly/ui";

const RetryRun = ({ org, runId }) => {
	const {
		fetch: requeue,
		body: newRun,
		isFetching: isQueueing,
		isFetched: isDone,
	} = useRequeueRun(org, runId);

	const handleClick = useCallback(() => requeue(), [requeue]);

	if (isDone) {
		return <span>All done! {}</span>;

	if (error) {
		return <span>{error.message}</span>;

	return (
			{isQueueing ? "Doing it..." : "Do it"}

export default RetryRun;


useRunConnection(org: string, runId: string): Object

This hook opens a WebSocket connection to the Runly API and will listen for any updates for a particular run. If the browser does not support WebSockets, it will fallback to other techniques to receive the run’s real-time updates. The hook returns the status of the connection and the run as it is updated.


org: string

The organization that the run to be monitored belongs to.

runId: string

The ID of the run to monitor.

import React from "react";
import { useRunConnection } from "@runly/ui";

const RunStatus = ({ org, runId }) => {
	const { run } = useRunConnection(org, runId);

	if (!run) {
		return <span>Connecting...</span>;

	return <pre>{JSON.stringify(run, null, 2)}</pre>;

export default RunStatus;