Skip to content

$ cat ~/projects/purrfect-match.md

Purrfect Match

A free, GPL-licensed plugin that gives a rescue’s public Petfinder listings a useful home on its own website. The rescue controls the copy, color, filters, cards, and next steps. No Petfinder API key or server-side secret is required.

View current source Read the build note
Reviewed source snapshot
34138c5
Version in source
1.7.1
Compatibility
WordPress 5.6+ / PHP 7.0+
Release boundary
No tagged GitHub release

$ git show 34138c5

The August 29 source pass

This reviewed 1.7.1 update is deliberately small. It makes the public widget hold together inside real WordPress themes and at the awkward widths between a phone and a full page.

  1. Host-theme resilience

    The widget now protects its type, tracking, and adoption-button label colors from overreaching WordPress theme rules.

  2. Better embed widths

    Filters stay balanced at medium widths, including two equal columns when Breed is hidden, then return to one column on phones.

  3. Quieter navigation

    The organization link disappears when it would only send someone back to the same site homepage.

Purrfect Match 1.7.1 source preview showing the CJ Paws banner, filter deck, and pet-card grid.
Source-controlled review fixture. This is the repository’s own WordPress preview with sample records, not a live list of adoptable cats. Inspect commit 34138c5

$ ./purrfect-match --org FL1629 --current

Try the public experience

This React island recreates the visitor-facing flow against CJ Paws’ public Petfinder data so it can be tried here. The plugin itself runs in WordPress; the source-controlled preview above shows that runtime. Filter the set, shuffle the order, read a story when one is available, or continue to the source profile. If live data is unavailable, the rescue’s adoption page remains the useful fallback.

CJ Paws Adoptable cats

Find your purr-fect match

Filter by breed, size, and age.

Visit cjpaws.org (opens in a new tab)

Refine your search

Choose one or more filters to narrow the current listing.

Choose a filter to narrow the list.

Finding current adoptable cats.

$ inspect --experience

A calmer path through the listings

Current main uses a dedicated filter deck, 4:3 photo crops that shift to 3:2 on narrow containers, aligned actions, and a container-aware card grid. It reveals more listings in clear batches instead of turning the page into a long wall of cards.

  1. Find the right listing

    Breed, size, and age filters work against the loaded set. Active choices stay visible as removable chips, and Shuffle offers another way through the same listings.

  2. Read before leaving

    When Petfinder supplies a description, an optional story panel opens over the card. Focus moves to Close, Escape dismisses it, and focus returns to the original control.

  3. Continue with context

    Cards can link to the full Petfinder profile and, when a rescue configures a form, pass the pet name and ID into an Apply to adopt link.

$ configure --instance

One shortcode, without hiding the controls

A rescue can set its defaults once in WordPress, then use a short shortcode on the page. Per-instance attributes can change the source, copy, listing type, status, reveal count, columns, and accent when a page needs something different. 

[purrfect_match organization="FL1629" type="cat"
  status="adoptable" per_page="24" columns="3" brand="#e93396"]

The repository is a standard WordPress plugin written in PHP, JavaScript, and CSS. It has no front-end build step.

Data and privacy

Public data, explicit boundaries

The plugin uses Petfinder’s public widget data source. It does not add accounts, analytics, form data, or a Petfinder API key. Petfinder and its photo CDN still receive ordinary browser connection metadata when they serve data or images. Purrfect Match is not affiliated with or endorsed by Petfinder.

Cache path

A ten-minute browser cache avoids repeat requests. Current source also ships with an optional shared WordPress cache enabled at a 120-minute default. Visitors may read the shared copy; only capable logged-in users can refresh it.

Search and accessibility

Optional JSON-LD identifies the rescue as an AnimalShelter and the visible pets as an ItemList. Semantic card headings, labelled controls, concise live-region updates, visible focus, keyboard story controls, and reduced-motion support are part of current source.

Independent community project

Coding for the cats

Purrfect Match is free, open-source, and separate from DepoStack. It is built for CJ Paws, with generic defaults so another rescue can adapt the same public-listing interface to its own identity and process.