usePost

Introduction

The usePost hook is a custom React Hook that simplifies the process of making POST requests and handling loading and errors. It is particularly useful when you need to send data to a server or API using the HTTP POST method and want to manage the loading and error states in your React components efficiently.

Usage

import React from "react";
import { usePost } from "@cannonui/reacthooks";

const TestUsePost = () => {
  const { res, err, isLoading } = usePost("http://localhost:3001/endpoint", {
    data: { a: "123" },
  });

  return (
    <>
      <div>isLoading: {isLoading ? "true" : "false"}</div>
      {err ? <div>Error: {err.message}</div> : <div>no error</div>}
      <div>res: {res ? res.data : ""}</div>
    </>
  );
};

export default TestUsePost;

Server Mockup using Express

Here’s an example of how you can set up a server mockup using Express to handle the POST request:

const express = require("express");
const app = express();

// Middleware to parse incoming JSON data
app.use(express.json());
app.use(
  express.urlencoded({
    extended: true,
  })
);
// POST endpoint to handle the request
app.post("/endpoint", (req, res) => {
  // Your server-side logic here to handle the POST request
  // For this mockup, we simply send a success response
  console.log(req.body); // {a: "123"}
  res.status(200).json({ message: "Data received successfully!" });
});

// Start the server on port 3001
app.listen(3001, () => {
  console.log("Server is running on http://localhost:3001");
});

Return Value

The usePost hook returns an object containing the following properties:

Name	Type	Description
res	ResponseData | null	The response data from the POST request, if any.
isLoading	boolean	A boolean indicating whether the request is loading.
err	Error | null	The error object in case of an error, if any.

Parameters

Name	Type	Description
url	string	The URL to which the POST request will be sent.
config	ExtendedRequestOptions (optional)	Additional configuration for the POST request.

Extended Request Options

The config parameter of the useGet hook allows you to customize the behavior of the GET request using the following properties:

Name	Type	Description
debounce(optional)	number	The time in milliseconds to wait before sending the request after the last trigger. Defaults to undefined.
polling(not available yet)	number	The interval in milliseconds between periodic GET requests. Allows periodic polling for updated data. Defaults to undefined.
tabular	TabularFormat (optional)	An optional object specifying the format of tabular data if your API returns data in a tabular format.
params(optional)	Record<string, string | number>	Additional parameters to be sent along with the GET request. Used for pagination or filtering.
data(optional)	any	Data to be sent as the request body. Useful for sending data in POST requests. Defaults to undefined.
files(optional)	File[] (optional)	An array of File objects representing files to be uploaded in a file upload request.
isFormData(optional)	boolean	A flag indicating whether the request body is of type FormData. Defaults to false.
timeout(optional)	number	The timeout duration in milliseconds for the GET request. If the request takes longer, it will be aborted. Defaults to undefined.
offline(not available yet)	boolean (optional)	A flag to indicate whether to store and serve the request from cache when the device is offline. Defaults to false.
onDataChunk(optional)	(chunk: ReadableStreamReadResult<any>)	A function to process chunks of data as they arrive when using streaming responses. Defaults to undefined.
onBefore(optional)	Array<(params: ExtendedRequestOptions) => any>	An array of functions to be executed before sending the GET request. Defaults to an empty array.
onSuccess(optional)	Array<(data: any, params: ExtendedRequestOptions) => any>	An array of functions to be executed when the GET request is successful. Defaults to an empty array.
onError(optional)	(error: Error)	A function to be executed when an error occurs during the GET request. Defaults to undefined.
onFinally(optional)	(params: ExtendedRequestOptions, data: any, error: any) => void	A function to be executed after the GET request is completed, regardless of success or error. Defaults to undefined.
maxRetry(optional)	number (optional)	The maximum number of times to retry the GET request in case of network errors. Defaults to undefined.
body(optional)	BodyInit | null	The request body to be sent with the GET request. Can be null.
cache(optional)	RequestCache	A string indicating how the request will interact with the browser’s cache to set request’s cache.
credentials (optional)	RequestCredentials	A string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. Sets request’s credentials.
headers (optional)	HeadersInit	A Headers object, an object literal, or an array of two-item arrays to set request’s headers.
integrity(optional)	string	A cryptographic hash of the resource to be fetched by request. Sets request’s integrity.
keepalive(optional)	boolean	A boolean to set request’s keepalive.
method (optional)	string	A string to set request’s method.
mode (optional)	RequestMode	A string to indicate whether the request will use CORS, or will be restricted to same-origin URLs. Sets request’s mode.
redirect(optional)	RequestRedirect	A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request’s redirect.
referrer(optional)	string	A string whose value is a same-origin URL, “about ”, or the empty string, to set request’s referrer.
referrerPolicy(optional)	ReferrerPolicy	A referrer policy to set request’s referrerPolicy.
signal (optional)	AbortSignal | null	An AbortSignal to set request’s signal.
window (optional)	null	Can only be null. Used to disassociate request from any Window.

Features

• Simplifies making POST requests in React components, making it easy to send data to servers or APIs.
• Automatically handles the loading state, allowing you to display a loading indicator while the POST request is ongoing.
• Provides an error object to handle and display any errors that occur during the POST request.
• Can be customized using the optional config parameter to add additional headers, set a timeout, or handle request retries.

Example

In the TestUsePost component, we use the usePost hook to make a POST request to the URL ”http://localhost:3001/endpoint”. The usePost hook handles the POST request and provides the res, isLoading, and err values to manage the loading and error states.

The component conditionally renders different content based on the state of the POST request. If the request is still loading, it displays “isLoading: true”. If there’s an error, it displays an error message with the error’s message. If the request is successful (res is not null), it displays the response data (res.data).

You can use the TestUsePost component in your application whenever you need to handle POST requests to send data to a server or API, and it will automatically manage the loading and error states, providing a smooth user experience.

Use Scenario

The usePost hook is useful in scenarios where you need to send data to a server or API using the POST method in a React component. It allows you to interact with APIs or servers to submit data while maintaining a smooth user experience by displaying loading indicators and handling errors gracefully.