### Install with Yarn Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md Install the Gravatar Quick Editor package using Yarn. ```bash yarn add @gravatar-com/quick-editor ``` -------------------------------- ### Install @gravatar-com/url-utils Source: https://context7.com/automattic/gravatar/llms.txt Install the URL utils library using npm. ```bash npm install @gravatar-com/url-utils ``` -------------------------------- ### Install with npm Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/url-utils/README.md Add the package to your project using npm. ```sh npm install --save @gravatar-com/url-utils ``` -------------------------------- ### Install with NPM Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md Install the Gravatar Quick Editor package using NPM. ```bash npm install @gravatar-com/quick-editor ``` -------------------------------- ### Start Local Development Server Source: https://github.com/automattic/gravatar/blob/trunk/docs/CONTRIBUTING.md Launches a local server to test the library in development mode. This should be run in a separate terminal from the build process. ```bash npm run start ``` -------------------------------- ### Install with UNPKG for Vanilla JavaScript Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/url-utils/README.md Import the library using a script tag for use in vanilla JavaScript projects. ```html ``` -------------------------------- ### Using the Example React component Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/url-utils/README.md Demonstrates how to use the Gravatar React component with and without specifying the size. ```html ``` -------------------------------- ### Install Dependencies with npm Source: https://github.com/automattic/gravatar/blob/trunk/docs/CONTRIBUTING.md Run this command in the root of the repository to install all necessary project dependencies. Ensure your Node.js version meets the minimum requirement specified in package.json. ```bash npm install ``` -------------------------------- ### Install with UNPKG Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md Import the Gravatar Quick Editor library using a script tag from UNPKG. Replace 'x.x.x' with the latest version number. ```html ``` -------------------------------- ### Install with NPM Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/hovercards/README.md Install the Gravatar Hovercards package using NPM. For React projects, also include react and react-dom. ```bash npm install @gravatar-com/hovercards ``` ```bash npm install add react react-dom @gravatar-com/hovercards ``` -------------------------------- ### Install with Yarn Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/hovercards/README.md Install the Gravatar Hovercards package using Yarn. For React projects, also include react and react-dom. ```bash yarn add @gravatar-com/hovercards ``` -------------------------------- ### React Installation via UNPKG Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/hovercards/README.md Include the hovercard styles and the React version of the library from UNPKG CDN. Ensure React and ReactDOM are imported before the library. The library is accessible as a global variable 'Gravatar'. ```html ``` -------------------------------- ### Vanilla JavaScript Installation via UNPKG Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/hovercards/README.md Include the hovercard styles and the Vanilla JavaScript library from UNPKG CDN. The library is accessible as a global variable 'Gravatar'. ```html ``` -------------------------------- ### GravatarQuickEditor Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md The GravatarQuickEditor class simplifies the setup process by automatically setting up event handlers to open the popup and update avatar elements on the page. ```APIDOC ## GravatarQuickEditor Constructor ### Description Initializes the GravatarQuickEditor with specified options to manage the Gravatar profile editing popup and avatar updates. ### Method `new GravatarQuickEditor(options: QuickEditorOptions)` ### Parameters #### Options - **`email`** (string) - Required - The email address associated with the Gravatar profile. - **`editorTriggerSelector`** (string) - Required - A CSS selector for the HTML element that triggers the editor popup. - **`avatarSelector`** (string) - Optional - A CSS selector for the HTML image element(s) that display the Gravatar avatar. These will be refreshed automatically upon update. - **`scope`** (Scope) - Optional - An array specifying which sections of the profile can be edited. - **`locale`** (string) - Optional - The locale setting for the Gravatar editor interface. - **`avatarRefreshDelay`** (number) - Optional - The delay in milliseconds before the avatar image is refreshed after an update. - **`utm`** (string) - Optional - A code used to determine where the Quick Editor is being used. ### Request Example ```typescript import { GravatarQuickEditor } from '@gravatar-com/quick-editor'; document.addEventListener( 'DOMContentLoaded', () => { new GravatarQuickEditor( { email: 'user@example.com', editorTriggerSelector: '#edit-profile', avatarSelector: '#gravatar-avatar', scope: [ 'avatars' ], } ); } ); ``` ### Notes When updating the avatar image, a `t` parameter with the current timestamp is added to the avatar URL to bypass the browser's cache. ``` -------------------------------- ### Use Gravatar CLI for URL Lookups Source: https://context7.com/automattic/gravatar/llms.txt The gravatar CLI command allows quick URL generation from the terminal. Install the package and use npx to run commands for avatar or profile URLs. ```bash # After installing and building npm install @gravatar-com/url-utils npx gravatar --help # Usage: cli [options] # Options: # --help, -h Show help # --avatar, -a Get avatar URL # --profile, -p Get profile URL # Get avatar URL npx gravatar --avatar sara@example.com # https://www.gravatar.com/avatar/259b65833bbadfd58ee66dde290489a6e51518339de4886d2331027751f0913a # Get profile URL npx gravatar --profile sara@example.com # https://www.gravatar.com/259b65833bbadfd58ee66dde290489a6e51518339de4886d2331027751f0913a # Get both npx gravatar --avatar --profile sara@example.com ``` -------------------------------- ### Example React component for Gravatar Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/url-utils/README.md A React component that uses the avatarUrl function to display a Gravatar image. It accepts email and an optional size prop. ```typescript import { avatarUrl } from '@gravatar-com/url-utils'; interface GravatarProps { email: string; size?: number; } const Gravatar = ( { email, size }: GravatarProps ) => { return ( User Avatar

); }; export default Gravatar; ``` -------------------------------- ### Navigate to Package Directory Source: https://github.com/automattic/gravatar/blob/trunk/docs/CONTRIBUTING.md Change your current directory to the specific package you intend to work on. Replace `[package-name]` with the actual name of the package. ```bash cd web/packages/[package-name] ``` -------------------------------- ### Project Directory Structure Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/url-utils/README.md Overview of the project's directory structure, including source files, distribution files, tests, and configuration files. ```sh . ├── README.md # You are here ├── dist # Output files (js and types) ├── lint-staged.config.js ├── package.json ├── src # Code │ ├── cli.ts # Very basic cli tool │ └── index.ts # The main library ├── tests # Unit tests, you should proabaly start here │ └── index.test.ts ├── webpack # Webpack config ├── tsconfig.json └── babel.config.ts ``` -------------------------------- ### Initialize and Attach Hovercards Instance Source: https://context7.com/automattic/gravatar/llms.txt Create a new Hovercards instance with customizable options and attach it to a DOM element to activate hovercards. The instance caches profiles to prevent duplicate API requests. Import the necessary CSS for styling. ```typescript import { Hovercards } from '@gravatar-com/hovercards'; import '@gravatar-com/hovercards/dist/style.css'; const hovercards = new Hovercards( { placement: 'right-start', // default; also: top, bottom, left, right, *-start, *-end offset: 10, // px gap between trigger element and card autoFlip: true, // flip direction when near viewport edge autoShift: true, // shift alignment when near viewport edge hideOnTargetClick: false, // hide card when trigger element is clicked delayToShow: 500, // ms before card appears delayToHide: 300, // ms before card disappears additionalClass: 'my-theme', // extra CSS class on the card root element myHash: 'abc123hash', // current user's hash — shows "Edit your profile" CTA i18n: { 'View profile →': 'Voir le profil →', 'Contact': 'Contact', 'Send money': 'Envoyer de l\'argent', }, onFetchProfileStart: ( hash ) => console.log( 'Fetching', hash ), onFetchProfileSuccess: ( hash, profileData ) => { console.log( 'Loaded profile for', profileData.displayName ); // profileData: { hash, avatarUrl, profileUrl, displayName, location, // description, jobTitle, company, headerImage, verifiedAccounts, // contactInfo, payments, backgroundColor } }, onFetchProfileFailure: ( hash, error ) => { // error: { code: number, message: string } console.error( `Failed for ${ hash }: ${ error.code } ${ error.message }` ); }, onHovercardShown: ( hash, cardEl ) => cardEl.setAttribute( 'data-visible', 'true' ), onHovercardHidden: ( hash, cardEl ) => cardEl.removeAttribute( 'data-visible' ), onCanShowHovercard: ( hash ) => hash !== 'blockedhash123', // return false to suppress onQueryHovercardRef: ( ref ) => ref.closest( '.avatar-wrapper' ) || ref, } ); document.addEventListener( 'DOMContentLoaded', () => { // Attach to all Gravatar images in a container hovercards.attach( document.getElementById( 'comments-section' ) ); // Or the entire page hovercards.attach( document.body ); // Exclude specific elements hovercards.attach( document.body, { ignoreSelector: '.no-hovercard img[src*="gravatar.com/avatar/"]', } ); // Use a custom data attribute instead of data-gravatar-hash hovercards.attach( document.getElementById( 'sidebar' ), { dataAttributeName: 'user-gravatar', // matches data-user-gravatar="" } ); // Detach when done (removes all event listeners) // hovercards.detach(); } ); ``` -------------------------------- ### Run Tests Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/url-utils/README.md Runs the test suite for the package using npm. ```sh npm run test ``` -------------------------------- ### new Hovercards(options) Source: https://context7.com/automattic/gravatar/llms.txt Creates a new Hovercards instance with configurable options. Use the `attach()` method to activate hovercards on DOM elements. The instance caches profiles to prevent redundant API calls. ```APIDOC ## `new Hovercards(options)` — Vanilla JS class constructor Creates a new Hovercards instance with the given configuration. Once created, call `attach()` to activate hovercards on a DOM element. The instance caches fetched profiles internally to avoid duplicate API requests. ```typescript import { Hovercards } from '@gravatar-com/hovercards'; import '@gravatar-com/hovercards/dist/style.css'; const hovercards = new Hovercards( { placement: 'right-start', // default; also: top, bottom, left, right, *-start, *-end offset: 10, // px gap between trigger element and card autoFlip: true, // flip direction when near viewport edge autoShift: true, // shift alignment when near viewport edge hideOnTargetClick: false, // hide card when trigger element is clicked delayToShow: 500, // ms before card appears delayToHide: 300, // ms before card disappears additionalClass: 'my-theme', // extra CSS class on the card root element myHash: 'abc123hash', // current user's hash — shows "Edit your profile" CTA i18n: { 'View profile →': 'Voir le profil →', 'Contact': 'Contact', 'Send money': 'Envoyer de l\'argent', }, onFetchProfileStart: ( hash ) => console.log( 'Fetching', hash ), onFetchProfileSuccess: ( hash, profileData ) => { console.log( 'Loaded profile for', profileData.displayName ); // profileData: { hash, avatarUrl, profileUrl, displayName, location, // description, jobTitle, company, headerImage, verifiedAccounts, // contactInfo, payments, backgroundColor } }, onFetchProfileFailure: ( hash, error ) => { // error: { code: number, message: string } console.error( `Failed for ${ hash }: ${ error.code } ${ error.message }` ); }, onHovercardShown: ( hash, cardEl ) => cardEl.setAttribute( 'data-visible', 'true' ), onHovercardHidden: ( hash, cardEl ) => cardEl.removeAttribute( 'data-visible' ), onCanShowHovercard: ( hash ) => hash !== 'blockedhash123', // return false to suppress onQueryHovercardRef: ( ref ) => ref.closest( '.avatar-wrapper' ) || ref, } ); document.addEventListener( 'DOMContentLoaded', () => { // Attach to all Gravatar images in a container hovercards.attach( document.getElementById( 'comments-section' ) ); // Or the entire page hovercards.attach( document.body ); // Exclude specific elements hovercards.attach( document.body, { ignoreSelector: '.no-hovercard img[src*="gravatar.com/avatar/"]', } ); // Use a custom data attribute instead of data-gravatar-hash hovercards.attach( document.getElementById( 'sidebar' ), { dataAttributeName: 'user-gravatar', // matches data-user-gravatar="" } ); // Detach when done (removes all event listeners) // hovercards.detach(); } ); ``` ``` -------------------------------- ### Hovercards.createHovercardSkeleton(options?) Source: https://context7.com/automattic/gravatar/llms.txt Statically builds a skeleton loading placeholder element. This is useful for displaying a loading state while profile data is being fetched asynchronously. ```APIDOC ## Hovercards.createHovercardSkeleton(options?) ### Description Static method to build a skeleton loading state element to display while profile data is being fetched asynchronously. ### Parameters #### Path Parameters - **options** (object) - Optional - Configuration options for the skeleton, including `additionalClass`. ### Request Example ```typescript import { Hovercards } from '@gravatar-com/hovercards'; import '@gravatar-com/hovercards/dist/style.css'; const container = document.getElementById( 'profile-slot' ); // Show skeleton immediately const skeleton = Hovercards.createHovercardSkeleton( { additionalClass: 'loading' } ); container.appendChild( skeleton ); // Simulate async fetch, then replace fetch( 'https://api.gravatar.com/v3/profiles/abc123def456' ) .then( ( r ) => r.json() ) .then( ( data ) => { container.removeChild( skeleton ); const card = Hovercards.createHovercard( { hash: data.hash, avatarUrl: data.avatar_url, profileUrl: data.profile_url, displayName: data.display_name, } ); container.appendChild( card ); } ); ``` ``` -------------------------------- ### Build Library in Development Mode with Watch Source: https://github.com/automattic/gravatar/blob/trunk/docs/CONTRIBUTING.md Compiles the code in development mode and continuously watches for file changes, recompiling automatically. This is useful for active development. ```bash npm run build:watch ``` -------------------------------- ### Initializing and Attaching Hovercards Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/hovercards/README.md Demonstrates how to initialize the Hovercards library and attach hovercards to Gravatar images or elements. You can attach to specific elements, containers, or the entire document body. The `ignoreSelector` option can be used to exclude certain elements. ```APIDOC ## Initialization and Attachment ### Description Initialize the `Hovercards` library and attach hovercard functionality to elements on the page. This can be done for individual elements, all elements within a container, or the entire document. ### Method ```javascript import { Hovercards } from '@gravatar-com/hovercards'; import '@gravatar-com/hovercards/dist/style.css'; document.addEventListener( 'DOMContentLoaded', () => { const hovercards = new Hovercards( { /* Options */ } ); // Attach to a specific Gravatar image element hovercards.attach( document.getElementById( 'avatar-1' ) ); // Attach to all Gravatar images within a specific container hovercards.attach( document.getElementById( 'container' ) ); // Attach to all Gravatar images across the entire page hovercards.attach( document.body ); // Attach with an ignore selector to exclude specific elements hovercards.attach( document.body, { ignoreSelector: '.ignore img[src*="gravatar.com/avatar/"]' } ); } ); ``` ### Usage with `data-gravatar-hash` Elements with the `data-gravatar-hash` attribute can also be converted into interactive hovercards. ### Method ```javascript import { Hovercards } from '@gravatar-com/hovercards'; import '@gravatar-com/hovercards/dist/styles.css'; document.addEventListener( 'DOMContentLoaded', () => { const hovercards = new Hovercards( { /* Options */ } ); // Attach to a specific element with data-gravatar-hash hovercards.attach( document.getElementById( 'ref-1' ) ); // Attach to all elements with data-gravatar-hash within a container hovercards.attach( document.getElementById( 'container' ) ); // Attach to all elements with data-gravatar-hash on the page hovercards.attach( document.body ); } ); ``` ``` -------------------------------- ### Common npm Scripts for Gravatar Development Source: https://github.com/automattic/gravatar/blob/trunk/docs/CONTRIBUTING.md A list of frequently used npm scripts for building, formatting, linting, and cleaning the project. These scripts help manage the development and release process. ```bash npm run start ``` ```bash npm run build ``` ```bash npm run build:dev ``` ```bash npm run build:watch ``` ```bash npm run format ``` ```bash npm run type-check ``` ```bash npm run lint:js ``` ```bash npm run lint:style ``` ```bash npm run lint:md:docs ``` ```bash npm run lint ``` ```bash npm run clean:dist ``` ```bash npm run clean:release ``` ```bash npm run clean ``` ```bash npm run release ``` -------------------------------- ### Initialize and Control GravatarQuickEditorCore Source: https://context7.com/automattic/gravatar/llms.txt Use this to manually control the editor popup and handle profile update events. Ensure the DOM is fully loaded before initializing. ```typescript import { GravatarQuickEditorCore } from '@gravatar-com/quick-editor'; document.addEventListener( 'DOMContentLoaded', () => { const editor = new GravatarQuickEditorCore( { email: 'user@example.com', scope: [ 'avatars', 'about', 'verified-accounts', 'contact-info' ], locale: 'en', onProfileUpdated: ( type ) => { // type: 'avatar_updated' | 'profile_updated' if ( type === 'avatar_updated' ) { const img = document.getElementById( 'profile-pic' ) as HTMLImageElement; const url = new URL( img.src ); url.searchParams.set( 't', Date.now().toString() ); img.src = url.toString(); } if ( type === 'profile_updated' ) { window.location.reload(); // refresh page to show new profile info } }, onOpened: () => { document.getElementById( 'overlay' ).style.display = 'block'; console.log( 'Editor popup opened' ); }, onClosed: () => { document.getElementById( 'overlay' ).style.display = 'none'; console.log( 'Editor popup closed' ); }, } ); document.getElementById( 'open-editor' ).addEventListener( 'click', () => { const opened = editor.open(); // returns false if popup was blocked if ( ! opened ) alert( 'Please allow popups for this site.' ); } ); document.getElementById( 'check-status' ).addEventListener( 'click', () => { console.log( 'Editor is open:', editor.isOpen() ); } ); document.getElementById( 'close-editor' ).addEventListener( 'click', () => { editor.close(); } ); // Open for a different email than configured (one-time override) document.getElementById( 'edit-other' ).addEventListener( 'click', () => { editor.open( 'other@example.com' ); } ); } ); ``` -------------------------------- ### Run Gravatar Command Line Tool Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/url-utils/README.md Executes the gravatar command line tool with different arguments. ```sh npm exec -- gravatar --avatar sara@example.com ``` ```sh npm exec -- gravatar --profile sara@example.com ``` -------------------------------- ### QuickEditorCoreOptions Type Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md Defines the configuration options for the Gravatar Quick Editor. ```APIDOC ## QuickEditorCoreOptions ### Description Type definition for the core options available when initializing or configuring the Gravatar Quick Editor. ### Fields - **`email`** (string) - Optional - The email address associated with the Gravatar profile to be edited. - **`scope`** (Scope) - Optional - An array specifying which sections of the profile are editable. Refer to the [Valid Scope Values](#valid-scope-values) section for available options. - **`locale`** (string) - Optional - The locale setting for the Gravatar editor interface, used to set the language of the UI. - **`onProfileUpdated`** ((type: ProfileUpdatedType) => void) - Optional - A callback function executed when the user successfully updates their profile. It receives a `ProfileUpdatedType` parameter, which can be `'avatar_updated'` or `'profile_updated'`. - **`onOpened`** (() => void) - Optional - A callback function executed when the editor popup is opened. - **`onClosed`** (() => void) - Optional - A callback function executed when the editor popup is closed. ``` -------------------------------- ### Build Javascript Files Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/url-utils/README.md Builds Javascript files from Typescript using npm. ```sh npm run build ``` -------------------------------- ### Hovercards Options Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/hovercards/README.md Configuration options for the `Hovercards` constructor to customize behavior, placement, and appearance. ```APIDOC ## Hovercards Options ### Description Customize the behavior and appearance of hovercards by passing an options object to the `Hovercards` constructor. ### Options - **`placement`** (string = `'right-start'`): The position of the hovercard relative to the target element. Possible values: `top`, `bottom`, `left`, `right`, `top-start`, `top-end`, `bottom-start`, `bottom-end`, `left-start`, `left-end`, `right-start`, `right-end`. - **`autoFlip`** (boolean = `true`): Automatically flips the hovercard's placement if there's not enough display space. - **`autoShift`** (boolean = `true`): Automatically shifts the hovercard's placement if there's not enough display space. - **`hideOnTargetClick`** (boolean = `false`): Hides the hovercard when its trigger element is clicked. - **`offset`** (number = `10`): The distance in pixels between the hovercard and the target element. - **`delayToShow`** (number = `500`): The delay in milliseconds before the hovercard appears. - **`delayToHide`** (number = `300`): The delay in milliseconds before the hovercard disappears. - **`i18n`** (Record< string, string >): An object for providing translated text strings. - **`additionalClass`** (string = `''`): Additional CSS class names to apply to the hovercard's outermost element for custom styling. - **`myHash`** (string = `''`): Enables personalized hovercard features for the current user, potentially showing customized options like 'Edit your profile'. - **`onQueryHovercardRef`** (function): A callback function triggered when the library queries a hovercard reference element. It receives the ref element and should return the modified element. ``` -------------------------------- ### Initialize Hovercards on Gravatar Images Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/hovercards/README.md Initializes hovercards for Gravatar images. Import the library and its CSS, then attach hovercards to specific images, containers, or the entire document body. Use `ignoreSelector` to exclude certain images. ```html

``` ```javascript import { Hovercards } from '@gravatar-com/hovercards'; // Import the hovercard styles import '@gravatar-com/hovercards/dist/style.css'; document.addEventListener( 'DOMContentLoaded', () => { // Start the hovercards feature with your preferred settings const hovercards = new Hovercards( { /* Options */ } ); // Make hovercards work on a specific Gravatar image hovercards.attach( document.getElementById( 'avatar-1' ) ); // Alternatively, make hovercards work on all Gravatar images within a specific container hovercards.attach( document.getElementById( 'container' ) ); // If you want hovercards on all Gravatar images across the entire page, use `document.body` as the target hovercards.attach( document.body ); // You can exclude certain Gravatar images from hovercards by using `ignoreSelector` hovercards.attach( document.body, { ignoreSelector: '.ignore img[src*="gravatar.com/avatar/"]' } ); } ); ``` -------------------------------- ### Initialize GravatarQuickEditor Source: https://context7.com/automattic/gravatar/llms.txt Instantiate GravatarQuickEditor with options to set up avatar editing functionality. This includes specifying the email, selectors for the editor trigger and avatar images, desired scope, locale, and refresh delay. ```typescript import { GravatarQuickEditor } from '@gravatar-com/quick-editor'; document.addEventListener( 'DOMContentLoaded', () => { new GravatarQuickEditor( { email: 'user@example.com', // Gravatar account email editorTriggerSelector: '#edit-avatar', // click this to open popup avatarSelector: '.user-avatar', // these are refreshed on avatar update scope: [ 'avatars', 'about', 'links' ], // sections shown in the editor locale: 'fr', // editor UI language (e.g. 'fr', 'es', 'de') avatarRefreshDelay: 1500, // ms to wait before refreshing (cache busting) } ); } ); // HTML: // //

// Clicking the button opens a 400×720 popup centered on screen. // After the user saves a new avatar, all .user-avatar images are refreshed with a timestamp. ``` -------------------------------- ### Define QuickEditorCoreOptions Type Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md Defines the configuration options for the Gravatar Quick Editor. Use this to customize the editor's behavior, such as setting the email, scope, locale, and defining callbacks for profile updates and editor events. ```typescript type QuickEditorCoreOptions = Partial< { email: string; scope: Scope; locale: string; onProfileUpdated: OnProfileUpdated; onOpened: OnOpened; } >; ``` -------------------------------- ### Initialize Hovercards with data-gravatar-hash Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/hovercards/README.md Converts elements with a `data-gravatar-hash` attribute into interactive hovercards. This method takes priority over image URLs. Import the library and its CSS, then attach hovercards to specific elements, containers, or the entire document. ```html

@Meow

@Woof

@Haha

``` ```javascript import { Hovercards } from '@gravatar-com/hovercards'; import '@gravatar-com/hovercards/dist/styles.css'; document.addEventListener( 'DOMContentLoaded', () => { // Start the hovercards feature with your preferred settings const hovercards = new Hovercards( { /* Options */ } ); // Attach hovercards on a specific image hovercards.attach( document.getElementById( 'ref-1' ) ); // Attach to all images within a container hovercards.attach( document.getElementById( 'container' ) ); // Attach to all images on the page hovercards.attach( document.body ); } ); ``` -------------------------------- ### Public Functions Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md Provides the public interface for interacting with the Gravatar Quick Editor. ```APIDOC ## Public Functions ### open #### Description Triggers the Gravatar Quick Editor popup. #### Signature `open(email?: string): boolean` #### Parameters - **`email`** (string) - Optional - The email address of the Gravatar profile to edit. If not provided, the editor may use a default or previously set email. #### Returns - `boolean` - `true` if the editor was successfully opened, `false` otherwise. ### close #### Description Closes the currently open Gravatar Quick Editor popup. #### Signature `close(): void` #### Parameters None. #### Returns None. ### isOpen #### Description Checks if the Gravatar Quick Editor popup is currently open. #### Signature `isOpen(): boolean` #### Parameters None. #### Returns - `boolean` - `true` if the popup is open, `false` otherwise. ``` -------------------------------- ### Gravatar CLI Tool Source: https://context7.com/automattic/gravatar/llms.txt Provides a command-line interface for generating Gravatar avatar and profile URLs. ```APIDOC ## gravatar CLI Tool ### Description The package ships a `gravatar` CLI command for quick URL lookups from the terminal. ### Usage ```bash # After installing and building npm install @gravatar-com/url-utils npx gravatar --help ``` ### Options - `--help`, `-h`: Show help. - `--avatar`, `-a`: Get avatar URL. - `--profile`, `-p`: Get profile URL. ### Examples #### Get avatar URL ```bash npx gravatar --avatar sara@example.com ``` #### Get profile URL ```bash npx gravatar --profile sara@example.com ``` #### Get both avatar and profile URLs ```bash npx gravatar --avatar --profile sara@example.com ``` ### Response #### Success Response (string) Prints the generated Gravatar URL to the console. ### Response Example ```bash # For --avatar option https://www.gravatar.com/avatar/259b65833bbadfd58ee66dde290489a6e51518339de4886d2331027751f0913a # For --profile option https://www.gravatar.com/259b65833bbadfd58ee66dde290489a6e51518339de4886d2331027751f0913a ``` ``` -------------------------------- ### Initialize GravatarQuickEditorCore Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md Initialize GravatarQuickEditorCore for advanced control. This allows manual triggering of the editor popup and custom handling of profile update events. Ensure the DOM is fully loaded before initialization. ```typescript import { GravatarQuickEditorCore } from '@gravatar-com/quick-editor'; document.addEventListener( 'DOMContentLoaded', () => { const quickEditorCore = new GravatarQuickEditorCore( { email: 'user@example.com', scope: [ 'avatars', 'about' ], onProfileUpdated: () => { console.log( 'Profile updated!' ); }, onOpened: () => { console.log( 'Editor opened!' ); }, } ); document.getElementById( 'edit-profile' ).addEventListener( 'click', () => { quickEditorCore.open(); } ); } ); ``` -------------------------------- ### GravatarQuickEditorCore Source: https://context7.com/automattic/gravatar/llms.txt Provides manual control over opening/closing the editor popup and receiving callbacks for profile update events. Use this when you need full programmatic control or want to integrate with your own state management. ```APIDOC ## `new GravatarQuickEditorCore(options)` — Low-level core editor ### Description Provides manual control over opening/closing the editor popup and receiving callbacks for profile update events. Use this when you need full programmatic control or want to integrate with your own state management. ### Constructor `new GravatarQuickEditorCore(options)` ### Parameters #### `options` (object) - **email** (string) - The email address associated with the Gravatar profile. - **scope** (array) - An array of strings specifying which parts of the profile can be edited (e.g., 'avatars', 'about', 'verified-accounts', 'contact-info'). - **locale** (string) - The language locale for the editor. - **onProfileUpdated** (function) - Callback function triggered when the profile is updated. Receives a `type` argument ('avatar_updated' | 'profile_updated'). - **onOpened** (function) - Callback function triggered when the editor popup is opened. - **onClosed** (function) - Callback function triggered when the editor popup is closed. ### Methods - **`open(email?: string)`**: Opens the editor popup. Returns `false` if the popup was blocked, otherwise `true`. An optional email can be provided to override the default email for a single session. - **`isOpen()`**: Returns `true` if the editor is currently open, `false` otherwise. - **`close()`**: Closes the editor popup. ### Example ```typescript import { GravatarQuickEditorCore } from '@gravatar-com/quick-editor'; document.addEventListener( 'DOMContentLoaded', () => { const editor = new GravatarQuickEditorCore( { email: 'user@example.com', scope: [ 'avatars', 'about', 'verified-accounts', 'contact-info' ], locale: 'en', onProfileUpdated: ( type ) => { // type: 'avatar_updated' | 'profile_updated' if ( type === 'avatar_updated' ) { const img = document.getElementById( 'profile-pic' ) as HTMLImageElement; const url = new URL( img.src ); url.searchParams.set( 't', Date.now().toString() ); img.src = url.toString(); } if ( type === 'profile_updated' ) { window.location.reload(); // refresh page to show new profile info } }, onOpened: () => { document.getElementById( 'overlay' ).style.display = 'block'; console.log( 'Editor popup opened' ); }, onClosed: () => { document.getElementById( 'overlay' ).style.display = 'none'; console.log( 'Editor popup closed' ); }, } ); document.getElementById( 'open-editor' ).addEventListener( 'click', () => { const opened = editor.open(); // returns false if popup was blocked if ( ! opened ) alert( 'Please allow popups for this site.' ); } ); document.getElementById( 'check-status' ).addEventListener( 'click', () => { console.log( 'Editor is open:', editor.isOpen() ); } ); document.getElementById( 'close-editor' ).addEventListener( 'click', () => { editor.close(); } ); // Open for a different email than configured (one-time override) document.getElementById( 'edit-other' ).addEventListener( 'click', () => { editor.open( 'other@example.com' ); } ); } ); ``` ``` -------------------------------- ### Initialize GravatarQuickEditor Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md Initialize the GravatarQuickEditor for simplified integration. This automatically sets up event handlers to open the popup and update avatar elements on the page. Ensure the DOM is fully loaded before initialization. ```typescript import { GravatarQuickEditor } from '@gravatar-com/quick-editor'; document.addEventListener( 'DOMContentLoaded', () => { new GravatarQuickEditor( { email: 'user@example.com', editorTriggerSelector: '#edit-profile', avatarSelector: '#gravatar-avatar', scope: [ 'avatars' ], } ); } ); ``` -------------------------------- ### GravatarQuickEditorCore Source: https://github.com/automattic/gravatar/blob/trunk/web/packages/quick-editor/README.md The GravatarQuickEditorCore class provides advanced control over the Gravatar Quick Editor functionality, allowing developers to trigger popup events and set up profile update callbacks. ```APIDOC ## GravatarQuickEditorCore Constructor ### Description Initializes the GravatarQuickEditorCore with specified options, providing advanced control over the editor's behavior and callbacks. ### Method `new GravatarQuickEditorCore(options: QuickEditorCoreOptions)` ### Parameters #### Options - **`email`** (string) - Required - The email address associated with the Gravatar profile. - **`scope`** (Scope) - Optional - An array specifying which sections of the profile can be edited. - **`onProfileUpdated`** (function) - Optional - Callback function executed when the Gravatar profile is updated. - **`onOpened`** (function) - Optional - Callback function executed when the editor popup is opened. - **`locale`** (string) - Optional - The locale setting for the Gravatar editor interface. - **`avatarRefreshDelay`** (number) - Optional - The delay in milliseconds before the avatar image is refreshed after an update. - **`utm`** (string) - Optional - A code used to determine where the Quick Editor is being used. ### Request Example ```typescript import { GravatarQuickEditorCore } from '@gravatar-com/quick-editor'; document.addEventListener( 'DOMContentLoaded', () => { const quickEditorCore = new GravatarQuickEditorCore( { email: 'user@example.com', scope: [ 'avatars', 'about' ], onProfileUpdated: () => { console.log( 'Profile updated!' ); }, onOpened: () => { console.log( 'Editor opened!' ); }, } ); document.getElementById( 'edit-profile' ).addEventListener( 'click', () => { quickEditorCore.open(); } ); } ); ``` ### Methods #### `open()` Opens the Gravatar Quick Editor popup. ### Notes When updating the avatar image, a `t` parameter with the current timestamp is added to the avatar URL to bypass the browser's cache. ``` -------------------------------- ### Hovercards.createHovercard(profileData, options?) Source: https://context7.com/automattic/gravatar/llms.txt Statically builds an HTMLDivElement hovercard from provided profile data. This is useful for embedding static hovercards directly into the page without automatic trigger logic. ```APIDOC ## Hovercards.createHovercard(profileData, options?) ### Description Static method to build a fully-rendered `HTMLDivElement` hovercard from profile data without any hover trigger logic. Useful for embedding static hovercards directly in the page. ### Parameters #### Path Parameters - **profileData** (object) - Required - An object containing profile information such as hash, avatarUrl, profileUrl, displayName, etc. - **options** (object) - Optional - Configuration options for the hovercard, including `additionalClass`, `myHash`, and `i18n`. ### Request Example ```typescript import { Hovercards } from '@gravatar-com/hovercards'; import '@gravatar-com/hovercards/dist/style.css'; const card = Hovercards.createHovercard( { hash: 'abc123def456', avatarUrl: 'https://www.gravatar.com/avatar/abc123def456?s=256', profileUrl: 'https://gravatar.com/myusername', displayName: 'Alice Example', location: 'San Francisco, CA', description: 'Open source contributor and coffee enthusiast.', jobTitle: 'Senior Engineer', company: 'Acme Corp', verifiedAccounts: [ { type: 'twitter', label: 'Twitter', icon: 'https://s.gravatar.com/icons/twitter.svg', url: 'https://twitter.com/alice', isHidden: false }, ], contactInfo: { email: 'alice@example.com', contact_form: 'https://alice.dev/contact', }, payments: { links: [ { label: 'PayPal', url: 'https://paypal.me/alice' } ], crypto_wallets: [ { label: 'Ethereum', address: '0xABCDEF...' } ], }, }, { additionalClass: 'featured-card', myHash: '', // set to current user's hash to enable "Edit your profile" CTA i18n: { 'View profile →': 'View Profile' }, } ); document.getElementById( 'profile-widget' ).appendChild( card ); // card is a