Skip to main content

Hooks API

This section provides a detailed reference for the custom React Hooks available within the library. These hooks are designed to encapsulate and reuse stateful logic, simplifying common tasks and interactions within a Blocklet environment.

useComponentInstalled

This hook checks whether one or more specified optional components (identified by their DIDs) are installed. It is essential for implementing features that rely on other Blocklets as dependencies. The hook provides the installation status and necessary URLs to prompt the user for installation if required.

Parameters

The hook accepts a single object with the following properties:

  • did string | string[] (required) — The Decentralized Identifier (DID) or an array of DIDs for the component(s) to check. A single string can contain multiple DIDs separated by ;;.
  • onInstalled function — An optional callback function that is triggered when all specified components are already installed.
  • onError function — An optional callback function that is triggered when one or more specified components are not installed.

Returns

It returns an object containing the installation state and related data:

  • optComponents array — An array of component objects that are not installed. Each object includes metadata such as meta.did, storeUrl, and installUrl.
  • installed boolean — A boolean value that is true if all specified components are installed and defined in the blocklet.yml, and false otherwise.
  • installStatus object — An object where keys are component DIDs and values are their current installation status (e.g., 'waiting', 'installing'). This state is updated via window.postMessage events.
  • setInstallStatus function — The state setter function to manually update the installStatus object.
  • definedInBlockletYML boolean — A boolean indicating whether the component is defined in the blocklet's configuration (blocklet.yml).

Example Usage

The following example demonstrates how to use useComponentInstalled to conditionally render a feature or a ComponentInstaller component if a dependency is missing.

"ComponentFeature.js"

javascript
import React from 'react';
import { useComponentInstalled, ComponentInstaller } from '@blocklet/ui-react';

const REQUIRED_DID = 'z8ia24z55nve2TSF5m1aZ5322d9f48a43D4a'; // Example DID

function ComponentFeature() {
  const { installed, optComponents } = useComponentInstalled({ did: REQUIRED_DID });

  if (!installed) {
    // Render the installer UI if the component is not present
    return <ComponentInstaller components={optComponents} />;
  }

  // Render the feature that depends on the installed component
  return (
    <div>
      <h2>My Feature</h2>
      <p>This feature requires the component with DID: {REQUIRED_DID}</p>
      {/* ... feature implementation ... */}
    </div>
  );
}

export default ComponentFeature;

useFollow

This hook manages the following relationship between the currently authenticated user and another user specified by their DID. It handles the API calls for following and unfollowing, and provides the current follow status.

Parameters

  • userDid string (required) — The DID of the user profile to check the follow status against.
  • t function (required) — A translation function used for displaying success or error messages (e.g., from react-i18next).
  • isMySelf boolean (required) — A boolean that should be set to true if the userDid belongs to the currently logged-in user.

Returns

Returns an object with the following properties:

  • followed boolean — Indicates if the current user is following the user specified by userDid. true if following, false otherwise.
  • followUser function — A stable function to call to follow the user. It handles the API request and updates the followed state on success.
  • unfollowUser function — A stable function to call to unfollow the user. It handles the API request and updates the followed state on success.

Example Usage

This example shows how to create a FollowButton component that displays a "Follow" or "Unfollow" action based on the relationship status.

"FollowButton.js"

javascript
import React from 'react';
import Button from '@mui/material/Button';
import { useTranslation } from 'react-i18next';
import { useFollow } from '@blocklet/ui-react/hooks';
import { useSession } from '@blocklet/did-connect-react';

function FollowButton({ profileDid }) {
  const { session } = useSession();
  const { t } = useTranslation();
  const isMySelf = session?.user?.did === profileDid;

  const { followed, followUser, unfollowUser } = useFollow({
    userDid: profileDid,
    t,
    isMySelf,
  });

  if (isMySelf) {
    return null; // Do not show button on your own profile
  }

  const handleClick = () => {
    if (followed) {
      unfollowUser();
    } else {
      followUser();
    }
  };

  return (
    <Button variant="contained" onClick={handleClick}>
      {followed ? t('profile.unfollow') : t('profile.follow')}
    </Button>
  );
}

export default FollowButton;

useMobile

A simple utility hook for creating responsive components. It leverages Material-UI's useMediaQuery to determine if the current viewport width is below a specified breakpoint.

Parameters

  • key number | Breakpoint (default: 'sm') — The Material-UI breakpoint key (e.g., 'xs', 'sm', 'md') or a pixel value to check against. The hook returns true if the screen width is smaller than this value.

Returns

Returns a boolean value: true if the viewport is smaller than the specified breakpoint, false otherwise.

Example Usage

This hook must be used within a component tree that is wrapped by a Material-UI ThemeProvider.

"ResponsiveComponent.js"

javascript
import React from 'react';
import Typography from '@mui/material/Typography';
import { ThemeProvider, createTheme } from '@mui/material/styles';
import { useMobile } from '@blocklet/ui-react/hooks';

// A component that uses the hook
function ResponsiveComponent() {
  const isMobile = useMobile({ key: 'md' }); // Check against the 'md' breakpoint

  return (
    <div>
      {isMobile ? (
        <Typography variant="h6">Mobile View</Typography>
      ) : (
        <Typography variant="h4">Desktop View</Typography>
      )}
      <p>Resize your browser window to see the content change.</p>
    </div>
  );
}

// The component must be wrapped in a ThemeProvider
const theme = createTheme();

function App() {
  return (
    <ThemeProvider theme={theme}>
      <ResponsiveComponent />
    </ThemeProvider>
  );
}

export default App;

By using these hooks, you can efficiently implement complex features with minimal boilerplate code. For more information on the components that might use these hooks, please see the Components documentation.