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:
The Decentralized Identifier (DID) or an array of DIDs for the component(s) to check. A single string can contain multiple DIDs separated by ;;.
An optional callback function that is triggered when all specified components are already installed.
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:
An array of component objects that are not installed. Each object includes metadata such as meta.did, storeUrl, and installUrl.
A boolean value that is true if all specified components are installed and defined in the blocklet.yml, and false otherwise.
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.
The state setter function to manually update the installStatus object.
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
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#
The DID of the user profile to check the follow status against.
A translation function used for displaying success or error messages (e.g., from react-i18next).
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:
Indicates if the current user is following the user specified by userDid. true if following, false otherwise.
A stable function to call to follow the user. It handles the API request and updates the followed state on success.
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
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 {See all 12 lines
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#
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
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() {See all 8 lines
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.