Skip to content

Latest commit

 

History

History
428 lines (306 loc) · 13.4 KB

README.md

File metadata and controls

428 lines (306 loc) · 13.4 KB
Raw
addreth


npm version bundle size License: MIT

What It Does

  • 👁 Display addresses in a compact way, while retaining the ability to see them in full.
  • 📋 Copy the address to the clipboard with a single click.
  • 👉 Check the address on the block explorer of your choice.
  • 🏷 ENS resolution works out of the box with wagmi (optional).
  • 🌈 Six themes to choose from or to customize as desired.
  • 🎹 Accessible: keyboard navigation and focus states work as expected.
  • 💆‍♀️ Zero configuration: just import and drop <Addreth /> in your app.
  • 🪚 Customizable: change the global configuration with <AddrethConfig /> (optional).
  • 📦 Small: 4.89 kB, styles and themes included, and no external dependencies.

How It Looks

With ENS name resolution Without ENS name resolution Popup

Design by Paty Davila

Installation

npm i -S addreth
pnpm add addreth
yarn add addreth

Getting Started

Import Addreth and add it to your app:

import { Addreth } from "addreth";

// If you are not using wagmi, import from "addreth/no-wagmi":
// import { Addreth } from "addreth/no-wagmi";

function App() {
  return (
    <main>
      <Addreth address="0x…" />
    </main>
  );
}

From this point, you could check out the demo page to see various examples of what can be done with the component, or keep reading this documentation to learn more about the available options.

Styles

As with most React components, addreth relies on a CSS foundation in order to work properly. There is no standard way to distribute CSS files with React components, so addreth provides three ways to handle this:

  • When used without <AddrethConfig/>, <Addreth /> renders its own CSS, this is to make it as easy as possible to get started and is fine performance wise for most cases. However, you might want to consider using <AddrethConfig /> if many instances of the component are being rendered simultaneously (see next point).

    import { Addreth } from "addreth";

function App() {
  return <Addreth />;
}

  • When the <AddrethConfig /> is rendered anywhere above <Addreth />, the top level one will take the responsibility to render styles once, making it more efficient.

    import { Addreth, AddrethConfig } from "addreth";

function App() {
  return (
    <AddrethConfig>
      <Addreth />
    </AddrethConfig>
  );
}

  • You can also bundle the CSS yourself if your bundler supports it, by importing "addreth/styles.css" and setting externalCss to true in the configuration to make the CSS rendering fully static. This is the most efficient way to render the styles.

    import { Addreth, AddrethConfig } from "addreth";
import "addreth/styles.css";

function App() {
  return (
    <AddrethConfig externalCss>
      <Addreth />
    </AddrethConfig>
  );
}

API

<Addreth />

The <Addreth /> component only requires the address prop to be set. It will display the address in a compact way while provide a convenient set of features. Multiple props are available to customize it in different ways:

address

The address prop is the only required prop, and it must be a valid Ethereum address.

<Addreth address="0x0000000000000000000000000000000000000000" />;
actions

The actions prop allows to control the action buttons inside the badge. It can be set to "all" (default), "copy", "explorer" or "none".

// Display the copy button only.
// The block explorer button will still appear on the popup.
<Addreth address="0x…" actions="copy" />;
ens

The ens prop allows to control whether to use the ENS name resolution, and it is enabled by default.

This is an alias for icon="identicon" and label="address".

<Addreth address="0x…" ens={false} />;
explorer

The explorer prop allows to generate the name and URL of a given block explorer (e.g. Etherscan).

<Addreth
  address="0x…"
  explorer={(address) => ({
    name: "Base",
    accountUrl: `https://basescan.com/address/${address}`,
  })}
externalCss

The externalCss prop allows to control whether to inject the CSS or not. This is useful if you want to bundle the Addreth CSS with your app. It defaults to false.

import { Addreth, AddrethConfig } from "addreth";
import "addreth/styles.css";

function App() {
  return (
    <AddrethConfig externalCss>
      <Addreth />
    </AddrethConfig>
  );
}
font and fontMono

The font and fontMono props allow to control the font names used for the badge and buttons. If fontMono is specified, it will be applied to the address specifically. If neither font nor fontMono are specified, the fonts will be inherited from the web page.

// Use the same font for the address and buttons
<Addreth address="0x…" font="Anonymous Pro" />;
icon

The icon prop allows to control the icon displayed in the badge. It can be set to "ens" (default), "identicon", false or null.

  • If set to "ens" and the app uses wagmi, the ENS avatar corresponding to the address, if it exists, will be displayed. Otherwise, the icon will fallback to "identicon".
  • If set to "identicon", the identicon corresponding to the address will be displayed.
  • If set to false or null, no icon will be displayed.
  • If set to a function, it will be called with the address as argument and must return either React element to replace the icon entirely, or a string to provide an image URL.
// Display the ENS avatar if available, otherwise display the identicon.
<Addreth address="0x…" icon="ens" />;

// Always display the identicon.
<Addreth address="0x…" icon="identicon" />;

// Do not display any icon.
<Addreth address="0x…" icon={false} />;

// Custom icon with a URL.
<Addreth
  address="0x…"
  icon={(address) => `https://example.com/identicon/${address}.svg`}
/>;

// Custom icon with a React element.
<Addreth
  address="0x…"
  icon={(address) => (
    <img src={`https://example.com/identicon/${address}.svg`} />
  )}
/>;
label

The label prop allows to control the label displayed in the badge. It can be set to "ens" (default), "address" or a function.

  • If set to "ens" and the app uses wagmi, the ENS name corresponding to the address, if it exists, will be displayed. Otherwise, the label will fallback to "address".
  • If set to "address", the address will be displayed, shortened to shortenAddress characters on each side (4 by default).
  • If set to a function, it will be called with the address as argument and must return a React node.
// Display the ENS name if available.
<Addreth address="0x…" label="ens" />;

// Always display the address.
<Addreth address="0x…" label="address" />;

// Custom label.
<Addreth
  address="0x…"
  label={(address) => <b>{address}</b>}
/>;
maxWidth

The maxWidth prop allows to control the maximum width of the badge. If not specified, the badge will adapt to its parent width.

// Limit the badge width to 200px.
<Addreth address="0x…" maxWidth={200} />;
popupNode

The popupNode prop allows to control the node used to render the popup. It defaults to document.body.

shortenAddress

The shortenAddress prop allows to control the number of first and last characters to show for the address. It defaults to 4. Set it to false to display the full address.

// Display the first and last 6 characters of the address.
<Addreth address="0x…" shortenAddress={6} />;
stylesId

The stylesId prop allows to control the ID attribute of the style element used to inject the CSS in the page. It defaults to "addreth-styles".

theme

The theme prop allows to control the theme used for the badge and buttons. It can be set to one of the provided themes, or used to define a custom theme.

Available themes:

  • light (default)
  • dark
  • unified-light
  • unified-dark
  • simple-light
  • simple-dark

You can also define a custom theme by passing an object. If base is provided, it will extend from that theme. Otherwise, it will extend the default theme (light), or the parent one if provided (see AddrethConfig to check how to define a parent config).

type ThemeDeclaration = {
  base?: ThemeName; // the theme to extend from

  // general
  textColor?: Color; // text color of the button and popup
  secondaryColor?: Color; // color of icons
  focusColor?: Color; // color of the focus ring
  fontSize?: number; // font size used everywhere

  // badge
  badgeBackground?: Color; // background color for the badge
  badgeRadius?: number; // radius used for the badge (if badgeGap is 0) or for individual buttons
  badgeIconRadius?: number; // radius for the badge icon (defaults to badgeRadius if not set)
  badgeGap?: number; // gap between badge itemstype
  badgeHeight?: number; // height of the badge
  badgePadding?: number; // inner padding of the badge
  badgeLabelPadding?: number; // padding inside the badge label

  // popup
  popupBackground?: Color; // background color of the popup
  popupRadius?: number; // radius of the popup
  popupShadow?: string; // shadow of the popup
};

See theme.ts for more details.

underline

Display the label underlined.

<Addreth address="0x…" underline />;
uppercase

Display the label in uppercase.

<Addreth address="0x…" uppercase />;

<AddrethConfig />

Having to wrap <Addreth /> in order to provide your desired default configuration can be tedious, which is why <AddrethConfig /> is provided. It allows to customize the default configuration of <Addreth /> and support the same props, except address.

import { Addreth, AddrethConfig } from "addreth";

function App() {
  return (
    <AddrethConfig font="Anonymous Pro" theme="dark">
      <Addreth address="0x…" />
    </AddrethConfig>
  );
}

Notes:

  • <AddrethConfig /> can be used multiple times in the same app, and its configuration will be merged.
  • The most top level <AddrethConfig /> will be responsible for rendering the CSS, so it is recommended to use it at the top level of your app even if you don’t intent to customize its configuration.

FAQ

Is it SSR-friendly?

Yes, both the component and its styles can be prerendered on the server.

Is it RSC-friendly?

Yes, Addreth is declared as a Client Component in this context. Check out this excellent article by Josh Comeau to learn more about how it works.

I am not using wagmi, can I still use Addreth?

Yes, wagmi is only used for ENS related features if present, but the component can work without by importing "addreth/no-wagmi":

import { Addreth } from "addreth/no-wagmi";

You can also use the mechanism of your choice to resolve the ENS name and avatar, and set these as icon and label:

import { Addreth } from "addreth/no-wagmi";
import { useENS } from "my-ens-library";

function App() {
  const { name, avatar } = useENS("0x…");
  return <Addreth address="0x…" icon={avatar} label={name} />;
}

License

MIT