useExport

The useExport hook is designed to make it easy to export data fetched from an API to an Excel file in a React application. It leverages react-query for API data management, axios for making requests, and custom utilities for exporting data to Excel.

This documentation provides an overview of the useExport hook, including:

• Installation: Instructions on how to install the useExport hook in your project.
• Usage: Detailed guidance on how to use the hook within your React application.
• Type Definitions: Definitions of the types used by the useExport hook for TypeScript support.
• API Structure: Information on the API structure and parameters required for utilizing the hook effectively.

Features

• Easy Integration: Seamlessly integrates with axios and react-query for fetching and managing data.
• Excel Export: Allows exporting data to Excel files with customizable formatting and headers.
• Customizable Data Handling: Format and filter data according to specific requirements before exporting.
• Translation Support: Supports translation of DTO values for internationalization, allowing for localized data presentation in exported files.
• Loading State: Provides a loading state to manage and display while exporting data.
• Flexible Table Configuration: Supports flexible table header and body configuration, including data injection, translation, and date formatting.

Installation

To use the useExport hook, you need to install the following dependencies:

npm install use-export

Usage Example

Here’s an example of how to use the useExport hook in a React component:

import useExport from "use-export"; // Adjust the import path as necessary

const ExportComponent = () => {
  const { handleExport, isPending } = useExport({
    api: "/api/endpoint", // API endpoint to fetch the data
    params: { filter: "value" }, // Optional query parameters
    nameFile: "employees", // Name of the exported Excel file
    injection: "data", // (Optional) key to inject from the API response
    tableHeaderCellFiltered: {
      thead: ["ID", "Name", "Status", "Date"], // Headers for Excel
      tbody: [
        {
          injection: "id", // Key to extract ID
        },
        {
          injection: "name", // Key to extract Name
        },
        {
            injection: "status",
            translate: [
            // Optional translations for Name
            { if: "pending", else: "قيد المعالجة" },
            { if: "approved", else: "تم الموافقة عليها" },
          ],
        }
        {
          injection: "createdAt", // Key to extract Date
          isDate: true, // Format the value as a date
        },
      ],
    },
  });

  return (
    <button onClick={handleExport} disabled={isPending}>
      {isPending ? "Exporting..." : "Export Data"}
    </button>
  );
};

API Reference

useExport(options: UseExportOptions)

Parameters

| Option | Type | Required | Description | | ------------------------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | | api | string | Yes | The API endpoint to fetch the data for export. | | params | Record<string, number \| string > | No | Parameters to pass to the API request. | | nameFile | string | Yes | The name of the exported Excel file. | | injection | string | No | Key to extract a specific part of the API response into the export process. | | tableHeaderCellFiltered | TableHeadLess | Yes | Configuration for the table headers and body that define how the data should be exported to Excel. |

Return Values

• handleExport: () => void
  Triggers the export process by making the API call, formatting the data, and exporting it as an Excel file.

• isPending: boolean
  Indicates whether the export process is ongoing, useful for showing loading indicators or disabling buttons.

Type Definitions

// Configuration for table headers and data mapping
type TableHeadLess = {
  thead: string[]; // Array of table headers (column titles).
  tbody: {
    injection: string; // Key for data injection from API response.
    translate?: { id: string; else: string }[]; // Optional translations for the injected data.
    isDate?: boolean; // Optional flag to format the value as a date.
  }[];
};

// Options for the useExport hook
export interface UseExportOptions {
  api: string; // API endpoint to fetch data from.
  params?: Record<string, number | string>; // Optional query parameters.
  nameFile: string; // Name of the exported Excel file.
  injection?: string; // Optional key for extracting a specific part of the response.
  tableHeaderCellFiltered: TableHeadLess; // Configuration for table headers and body for Excel export.
}

// Hook return type
declare function useExport(options: UseExportOptions): {
  handleExport: () => void; // Function to trigger the export process.
  isPending: boolean; // Boolean indicating the pending state.
};

export default useExport;