{"_id":"@amax/amaxwallet-adapter-react-hooks","name":"@amax/amaxwallet-adapter-react-hooks","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@amax/amaxwallet-adapter-react-hooks","version":"1.1.0","description":"A `useWallet()` hook to make it easy to interact with Tron wallets.","keywords":["armoniax","amaxScan","react-hooks"],"author":{"name":"armoniax"},"repository":{"type":"git","url":"git+https://github.com/armoniax/amaxjs.git#main"},"license":"MIT","type":"module","sideEffects":false,"engines":{"node":">=16","pnpm":">=7"},"main":"./lib/cjs/index.js","module":"./lib/esm/index.js","types":"./lib/types/index.d.ts","exports":{"require":"./lib/cjs/index.js","import":"./lib/esm/index.js","types":"./lib/types/index.d.ts"},"publishConfig":{"access":"public"},"peerDependencies":{"react":"*","react-dom":"*"},"dependencies":{"@amax/abstract-adapter":"^1.1.0"},"devDependencies":{"@types/react":"^18.0.26","@types/scheduler":"0.16.2","@types/react-dom":"^18.0.6","jest-localstorage-mock":"^2.4.22","react":"^18.2.0","react-dom":"^18.2.0","shx":"^0.3.4"},"scripts":{"clean":"shx mkdir -p lib && shx rm -rf lib","package":"shx echo '{ \"type\": \"commonjs\" }' > lib/cjs/package.json","test":"jest"},"bugs":{"url":"https://github.com/armoniax/amaxjs/issues"},"homepage":"https://github.com/armoniax/amaxjs/tree/main#readme","_id":"@amax/amaxwallet-adapter-react-hooks@1.1.0","_integrity":"sha512-oOjFVFNzijdEwzD0+AquZjLib7fXJemEBI2otE3CHgxu+lUdVgKFBvzxiC4WP+RzaVzNJVL66vdw5hGPYakofQ==","_resolved":"/private/var/folders/3f/51_3qrs158j01hsttw5lg5940000gn/T/57fab1c35570a39a3a4f3452a9c5fab1/amax-amaxwallet-adapter-react-hooks-1.1.0.tgz","_from":"file:amax-amaxwallet-adapter-react-hooks-1.1.0.tgz","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-oOjFVFNzijdEwzD0+AquZjLib7fXJemEBI2otE3CHgxu+lUdVgKFBvzxiC4WP+RzaVzNJVL66vdw5hGPYakofQ==","shasum":"51ac94c2f56e4766c437b9b5369ca46b84c67aa6","tarball":"https://registry.npmjs.org/@amax/amaxwallet-adapter-react-hooks/-/amaxwallet-adapter-react-hooks-1.1.0.tgz","fileCount":33,"unpackedSize":79988,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDN9CS5GLWs0dOqLESJn0KE0Do51IITd/UUNmrVjxZNaAIhAMQgwYwooJM3rnsie7w480skpaZTp8fOLnCg53FqL+Jo"}]},"_npmUser":{"name":"armoniametachain","email":"aplink2022@gmail.com"},"directories":{},"maintainers":[{"name":"armoniametachain","email":"aplink2022@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/amaxwallet-adapter-react-hooks_1.1.0_1718853147077_0.643487484300578"},"_hasShrinkwrap":false}},"time":{"created":"2024-06-20T03:12:26.951Z","1.1.0":"2024-06-20T03:12:27.257Z","modified":"2024-06-20T03:12:27.531Z"},"maintainers":[{"name":"armoniametachain","email":"aplink2022@gmail.com"}],"description":"A `useWallet()` hook to make it easy to interact with Tron wallets.","homepage":"https://github.com/armoniax/amaxjs/tree/main#readme","keywords":["armoniax","amaxScan","react-hooks"],"repository":{"type":"git","url":"git+https://github.com/armoniax/amaxjs.git#main"},"author":{"name":"armoniax"},"bugs":{"url":"https://github.com/armoniax/amaxjs/issues"},"license":"MIT","readme":"# @amax/amaxwallet-adapter-react-hooks\n\n`@amax/amaxwallet-adapter-react-hooks` provides a `useWallet()` hook which will make it easy to \"Connect Wallet\" and listen to the state change for developers.\n\n## Installation\n\n```bash\nnpm install @amax/amaxwallet-adapter-react-hooks @amax/abstract-adapter @amax/amaxwallet-adapters\n```\n\n## Usage\n\n`@amax/amaxwallet-adapter-react-hooks` uses [`Context` of React](https://reactjs.org/docs/context.html) to maintain a shared data. So developers need to wrap `App` content within the `WalletProvider`.\n\nYou can provide a `onError` callback to handle various errors such as `WalletConnectionError`, `WalletNotFoundError`.\n\n```jsx\nimport { useWallet, WalletProvider } from '@amax/amaxwallet-adapter-react-hooks';\nimport { WalletDisconnectedError, WalletError, WalletNotFoundError } from '@amax/abstract-adapter';\nimport toast, { Toaster } from 'react-hot-toast';\n\nfunction App() {\n    // use `react-hot-toast` npm package to notify user what happened here\n    function onError(e: WalletError) {\n        if (e instanceof WalletNotFoundError) {\n            toast.error(e.message);\n        } else if (e instanceof WalletDisconnectedError) {\n            toast.error(e.message);\n        } else toast.error(e.message);\n    }\n    return (\n        <WalletProvider onError={onError}>\n            <ConnectComponent></ConnectComponent>\n            <Profile></Profile>\n        </WalletProvider>\n    );\n}\nfunction ConnectComponent() {\n    const { connect, disconnect, select, connected } = useWallet();\n    return (<div>\n      <button type=\"button\" onClick={() => select('Armodillo' as any)}> Select Armodillo</button>\n      <button type=\"button\" disabled={connected} onClick={connect}>Connect</button><br>\n      <button type=\"button\" disabled={!connected} onClick={disconnect}>Disconnect</button>\n    </div>);\n}\nfunction Profile() {\n    const { account, connected, wallet } = useWallet();\n    return (<div>\n        <p> <span>Connection Status:</span> {connected ? 'Connected' : 'Disconnected'}</p>\n        <p> <span>Your selected Wallet:</span> {wallet?.adapter.name} </p>\n        <p> <span>Your Account:</span> {JSON.stringify(account)} </p>\n    </div>);\n}\n```\n\n## `WalletProvider`\n\n`WalletProvider` and `useWallet` work together like `Context.Provider` and `useContext()`. There is a `WalletProviderContext` underlying which maintains some state and can be obtained with `useWallet`. So developers need to wrap application components with `WalletProvider`.\n\n```jsx\nimport { useWallet, WalletProvider } from '@amax/amaxwallet-adapter-react-hooks';\nfunction App() {\n    return <WalletProvider>/* here is application components */</WalletProvider>;\n}\n```\n\n### Props\n\n#### adapters:\n\n-   Required: `false`\n-   Type: `Adapter[]`\n-   Default: `[]`\n\nUsed to specify what wallet adapters are supported. All wallet adapters can be imported from `@amax/amaxwallet-adapters` package or their standalone package.\n\n-   Example\n    ```jsx\n    import { useWallet, WalletProvider } from '@amax/amaxwallet-adapter-react-hooks';\n    import { ArmodilloAdapter } from '@amax/amaxwallet-adapters';\n    function App() {\n        const adapters = useMemo(() => [new ArmodilloAdapter()]);\n        return <WalletProvider adapters={adapters}>/* here is application components */</WalletProvider>;\n    }\n    ```\n\n#### onError\n\n-   Required: `false`\n-   Type: `(error: WalletError): void`\n-   Default: `function(error) { console.error(error); }`\n\nUsed to handle errors occured when use wallet. Developers can use the callback to tell users what happened according to the `error` type. All error types can be found [here](https://github.com/tronprotocol/tronwallet-adapter/blob/main/packages/adapters/abstract-adapter/src/errors.ts).\n\n-   Example\n    ```jsx\n    functon onError(e) {\n    if (e instanceof WalletNotFoundError) {\n            console.error(e.message);\n        } else if (e instanceof WalletDisconnectedError) {\n            console.error(e.message);\n        } else console.error(e.message);\n    }\n    ```\n\n#### autoConnect\n\n-   Required: `false`\n-   Type: `boolean`\n-   Default: `true`\n\nWhether connect to the specified wallet automatically when loading the page and selecting a wallet.\n\n#### disableAutoConnectOnLoad\n\n-   Required: `false`\n-   Type: `boolean`\n-   Default: `false`\n\nWhen `autoConnect` enabled, whether automatically connect to current selected wallet when loading the page.\nIf you don't want to connect the wallet when page is first loaded, set `disableAutoConnectOnLoad: true`.\n\n#### localStorageKey\n\n-   Required: `false`\n-   Type: `string`\n-   Default: `amaxAdapterName`\n\nSpecified the key used to cache wallet name in `localStorage`. When user select a wallet, applications will cache the wallet name to localStorage.\n\n#### Event handlers\n\nYou can provide event handlers for listen adapter events, such as `connect`,`disconnect`,`accountsChanged`. Available event handlers and their types are as follows:\n\n-   `readyStateChanged: (readyState: 'Found' | 'NotFound') => void`: Called when current adapter emits `readyStateChanged` event.\n-   `onConnect: (address: string) => void`: Called when current adapter emits `connect` event.\n-   `onDisconnect: () => void`: Called when current adapter emits `disconnect` event.\n-   `onAccountsChanged: (newAddress: string; preAddress?: string) => void`: Called when current adapter emits `accountsChanged` event.\n-   `onChainChanged: (chainData: unknow) => void`: Called when current adapter emits `chainChanged` event.\n\nAn event handler named `onAdapterChanged` is also avaliable to get noticed when selected adapter is changed.\n\n-   `onAdapterChanged: (adapter: Adapter | null) => void`: Called when current adapter is changed.\n\nHere is an example:\n\n```jsx\nimport { useWallet, WalletProvider } from '@amax/amaxwallet-adapter-react-hooks';\nimport { ArmodilloAdapter } from '@amax/amaxwallet-adapters';\nfunction App() {\n    const adapters = useMemo(() => [new ArmodilloAdapter()]);\n    const onAccountsChanged = useCallback((curAddr, preAddr) => {\n        console.log('new address is: ', curAddr, ' previous address is: ', preAddr);\n    }, []);\n    return (\n        <WalletProvider adapters={adapters} onAccountsChanged={onAccountsChanged}>\n            /* here is application components */\n        </WalletProvider>\n    );\n}\n```\n\n## `useWallet()`\n\n`useWallet` is a react hook providing a set of properties and methods which can be used to select and connect wallet, get wallet state and so on.\n\n> `useWallet()` must be used in the descendant components of `WalletProvider`!\n\n### ReturnedValue\n\n#### `autoConnect`\n\n-   Type: `boolean`\n    Synchronous with `autoConnect` property passed to `WalletProvider`.\n\n#### `disableAutoConnectOnLoad`\n\n-   Type: `boolean`\n    Synchronous with `disableAutoConnectOnLoad` property passed to `WalletProvider`.\n\n#### `wallet`\n\n-   Type: `Wallet | null`\n    The wallet current selected. If no wallet is selected, the value is `null`.\n\n`Wallet` is defined as follow:\n\n```typescript\ninterface Wallet {\n    adapter: Adapter; // wallet adapter\n    state: AdapterState;\n}\nenum AdapterState {\n    NotFound = 'NotFound',\n    Disconnect = 'Disconnected',\n    Connected = 'Connected',\n}\n```\n\n#### `address`\n\n-   Type: `string | null`\n    Address of current selected wallet. If no wallet is selected, the value is `null`.\n\n#### `wallets`\n\n-   Type: `Wallet[]`\n    Wallet list based on current used adapters when initial `WalletProvider`.\n\n#### `connecting`\n\n-   Type: `boolean`\n    Indicate if is connecting to the wallet.\n\n#### `connected`\n\n-   Type: `boolean`\n    Indicate if is connected with the wallet.\n\n#### `disconnecting`\n\n-   Type: `boolean`\n    Indicate if is connecting to the wallet.\n\n### Methods\n\n#### select\n\n-   Type: `(walletAdapterName: AdapterName) => void`\n    Select a wallet by walletAdapterName. Valid adapters can be found [here](https://github.com/tronprotocol/tronwallet-adapter/tree/main/packages/adapters/adapters)\n\n#### connect\n\n-   Type: `() => Promise<void>`\n    Connect to current selected wallet.\n\n#### disconnect\n\n-   Type: `() => Promise<void>`\n    Disconnect from current selected wallet.\n\n### transact\n\n-   Type: `(actions: Action[]): Promise<TransactResult>`\n    push a transaction.\n\n### signMessage\n\n-   Type: `(message: string) => Promise<string>`\n    Sign a message.\n\n### Example\n\n```js\nimport { useWallet } from '@amax/amaxwallet-adapter-react-hooks';\nimport { AdapterName } from '@tronweb3/tronwallet-abstract-adapter';\n\nfunction Content() {\n    const { connect, disconnect, select, connected } = useWallet();\n    return (\n        <div>\n            <button type=\"button\" onClick={() => select('Armodillo')}>\n                Select Armodillo\n            </button>\n            <button type=\"button\" disabled={connected} onClick={connect}>\n                Connect\n            </button>\n            <button type=\"button\" disabled={!connected} onClick={disconnect}>\n                Disconnect\n            </button>\n        </div>\n    );\n}\n```\n","readmeFilename":"README.md"}