C3 AI Documentation Home

Fetch data with useC3Action

Use the useC3Action hook when a component fetches data at runtime and manages it locally.

This pattern works well when:

  • Only one component needs the data
  • The data changes based on user input or route state
  • You want to avoid shared application state

The hook handles backend calls, tracks request status, and stores results internally—no Redux setup needed.

When you build a UI component, you often need to interact with the backend to fetch or write data. You can handle this in several ways — by using native fetch, managing application state with tools like Redux, or calling backend actions directly with useC3Action. This topic focuses on the useC3Action approach, which lets your component fetch data at runtime and manage it locally with minimal setup.

Define the WindTurbine Type

To follow the examples in this topic, update the WindTurbine Type to expose useful turbine fields and include an action to fetch records by status.

Type
// {package}/src/entity/WindTurbine.c3typ

entity type WindTurbine {

  /**
   * The name or serial number of the wind turbine.
   */
  serialNumber: string

  /**
   * The company that manufactured the turbine.
   */
  manufacturer: string

  /**
   * Physical location of the turbine.
   */
  location: string

  /**
   * The date the turbine was manufactured.
   */
  manufacturerDate: datetime

  /**
   * The date the turbine was installed and made operational.
   */
  installationDate: datetime

  /**
   * Operational status of the turbine (0 = offline, 1 = running).
   */
  status: int

  /**
   * Fetch all turbines with a specific status.
   */
  getWindTurbineByStatus: function(status: int): [WindTurbine] js-server
}
JavaScript
// {package}/src/entity/WindTurbine.js
function getWindTurbineByStatus(status) {
  return WindTurbine.fetch(Filter.eq('status', status)).objs;
}

Fetch records and display them in a table

This component uses useC3Action to fetch WindTurbine records where status = 1 (RUNNING). The component updates the state when data loads and renders the result in a simple HTML table.

You can always use native APIs like fetch. If you take that route, you must construct URLs manually, handle asynchronicity and errors, and update client-side state yourself. That also means integrating Redux or a similar solution if you want to share or persist the fetched data.

In contrast, useC3Action simplifies the entire flow. The hook takes care of sending the request, tracking its status, and returning the result—all without boilerplate.

TypeScript
// {package}/ui/c3/src/customInstances/WindTurbine.TurbineTable.tsx

import React from 'react';
import { useC3Action } from '@c3/ui/UiSdlUseC3Action';

const WindTurbineTable = () => {
  const [rows, setRows] = React.useState([]);
  const [refresh, setRefresh] = React.useState(0);

  const actionSpec = {
    typeName: 'WindTurbine',
    actionName: 'getWindTurbineByStatus',
    method: 'POST',
    argsArray: [1], // Pass status as positional argument
  };

  const response = useC3Action(actionSpec);

  React.useEffect(() => {
    if (response.status === 'done') {
      setRows(response.data);
    }
  }, [response]);

  return (
    <>
      <button onClick={() => setRefresh(refresh + 1)}>Refresh</button>
      <table>
        <thead>
          <tr>
            <th>Serial</th>
            <th>Manufacturer</th>
            <th>Location</th>
            <th>Installed</th>
            <th>Status</th>
          </tr>
        </thead>
        <tbody>
          {rows.map((row) => (
            <tr key={row.id}>
              <td>{row.serialNumber}</td>
              <td>{row.manufacturer}</td>
              <td>{row.location}</td>
              <td>{new Date(row.installationDate).toLocaleDateString()}</td>
              <td>{row.status === 1 ? 'RUNNING' : 'OFFLINE'}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </>
  );
};

export default WindTurbineTable;

Sample backend response

The backend returns a list of turbine objects. Each record contains fields you can use in tables, charts, or other views.

JSON
[
  {
    "id": "turbine_01",
    "serialNumber": "SN-001",
    "manufacturer": "GE",
    "location": "Texas",
    "manufacturerDate": "2012-06-12T00:00:00.000Z",
    "installationDate": "2013-02-01T00:00:00.000Z",
    "status": 1
  },
  {
    "id": "turbine_03",
    "serialNumber": "SN-003",
    "manufacturer": "Siemens",
    "location": "Colorado",
    "manufacturerDate": "2015-04-20T00:00:00.000Z",
    "installationDate": "2015-12-05T00:00:00.000Z",
    "status": 1
  }
]

Use useC3Action when a single component needs to fetch data and manage it locally. This hook handles the request automatically, tracks the status, and returns the result.

Was this page helpful?