react-ipfs-url

Grab a URL from a IPFS path by using URL.createObjectURL.

Installation

$ npm install react-ipfs-url

This library is written in modern JavaScript and is published in both CommonJS and ES module transpiled variants. If you target older browsers please make sure to transpile accordingly.

Usage

With <IpfsUrl> component:

import React from 'react';
import { IpfsUrl } from 'react-ipfs-url';

const ipfs = /* your ipfs node, perhaps provide it via context */;

const SomeComponent = () => (
    <IpfsUrl ipfs={ ipfs } path="/ipfs/QmQuMzeovz...">
        { ({ status, value }) => (
            <>
                { status === 'pending' && 'Loading...' }
                { status === 'rejected' && 'Oops, failed to load' }
                { status === 'fulfilled' && <img src={ value } alt="" /> }
            <>
        ) }
    </IpfsUrl>
);

With useIpfsUrl() hook:

import React from 'react';
import { useIpfsUrl } from 'react-ipfs-url';

const ipfs = /* your ipfs node, perhaps provide it via context */;

const SomeComponent = () => {
    const [urlStatus, urlValue] = useIpfsUrl(ipfs, '/ipfs/QmQuMzeovz..');

    return (
        <>
            { status === 'pending' && 'Loading...' }
            { status === 'rejected' && 'Oops, failed to load' }
            { status === 'fulfilled' && <img src={ value } alt="" /> }
        </>
    );
};

API

• <IpfsUrl>
• useIpfsUrl(ipfs, path, [options])

IpfsUrl

The <IpfsUrl> component allows you to conditionally render children based on the url status and fulfillment/rejection value. It leverages the render props technique to know what to render.

Props

All properties from react-promiseful are also valid.

ipfs

Type: object

The ipfs node to be used.

input

Type: string

A valid IPFS path, hash or a provider URL, such as a gateway URL or an Infura URL.

⚠️ At the moment, IPNS paths are not supported for the ipfs and ipfsOffline providers: https://github.com/ipfs-shipyard/react-ipfs-url/issues/2

⚠️ There's no support for fully qualified domains URLs yet: https://github.com/ipfs-shipyard/react-ipfs-url/issues/4

stategy

Type: string
Default: input-first

The strategy to use when resolving a valid URL.

• input-first: Use the provider associated with the input first and fallback to resolving with IPFS.
• ipfs-first: Use IPFS to resolve the URL first and fallback to resolving with the provider associated with the input
• ipfs-offline-first: Use offline IPFS first and fallback to resolving with the provider, followed by the online IPFS.
• ipfs-only: Only use IPFS to resolve the URL, even if input comes from another provider
• ipfs-offline-only: Only use IPFS (offline) to resolve the URL, even if input comes from another provider

checkTimeout

Type: object
Default: { gateway: 12500, infura: 12500, ipfsOffline: 5000, ipfs: 180000 }

The max time to spend checking for the existence of the content on providers.

disposeDelayMs

Type: number
Default: 60000

The delay in which object urls created with URL.createObjectURL are revoked when they are no longer used.

children

Type: Function

A render prop function with the following signature:

(state) => {}

The state argument is an object that contains the following properties:

• status is one of none (when there's no promise), pending, rejected, fulfilled
• value is either the fulfillment value (url) or the rejection value
• withinThreshold indicating if we are still within the configured thresholdMs

See react-promiseful for more info.

useIpfsUrl(ipfs, path, [options])

The hook version of the <IpfsUrl> component. The options available to both are exactly the same.

const urlState = useIpfsUrl(ipfs, '/ipfs/QmQuMzeovz..');

The returned value from the hook is the url promise state, an object that contains the following properties:

• status is one of none (when there's no promise), pending, rejected, fulfilled
• value is either the fulfillment value (url) or the rejection value
• withinThreshold indicating if we are still within the configured thresholdMs

See react-promiseful for more info.

Tests

$ npm test
$ npm test -- --watch # during development

License

Released under the MIT License.