PL8SRCH - Australian Vehicle Registration Search

React Component

npm install @cartbot/plate-search

import PlateSearch from "@cartbot/plate-search";

<PlateSearch
  apiKey="YOUR_API_KEY"
  themeColor="#10b981"
  useGeolocation="true"
/>;

Note: CSS is automatically included via Shadow DOM - no separate stylesheet import needed! All styles are perfectly isolated and won't affect your application.

TypeScript

Full TypeScript support is included:

import PlateSearch, { PlateSearchProps } from "@cartbot/plate-search";

const MyComponent = () => {
  return (
    <PlateSearch
      apiKey="YOUR_API_KEY"
      themeColor="#10b981"
      responsive={true}
      onVehicleSelect={(vehicle) => console.log(vehicle)}
    />
  );
};

Customizing Action Button

You can customize the "Show Products" button label:

<PlateSearch
  apiKey="YOUR_API_KEY"
  productsUrl="/products"
  actionButtonLabel="View Parts"
/>

Inline (Embedded) Mode

By default, PlateSearch renders as a modal. To render it inline (embedded in-place), set displayMode="inline":

<PlateSearch
  apiKey="YOUR_API_KEY"
  displayMode="inline"
/>

Session Limits (Local Browser)

The component includes client-side session throttling for unique plate/state lookups:

• Default: 10 unique lookups per rolling minute (per browser session)
• Demo mode: 2 unique lookups per day (per browser session), plus the minute limit above

Enable demo mode:

<PlateSearch
  apiKey="YOUR_API_KEY"
  demoMode={true}
/>

Controlled Modal State

Control the modal open/close state from your own UI using either controlled props or imperative methods:

Option 1: Controlled Props (Recommended)

import { useState } from "react";
import PlateSearch from "@cartbot/plate-search";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Search by Registration</button>

      <PlateSearch
        apiKey="YOUR_API_KEY"
        isOpen={isOpen}
        onOpenChange={setIsOpen}
        hideDefaultButton
        onModalClose={() => console.log("Modal closed")}
      />
    </>
  );
}

Option 2: Imperative Methods (via ref)

import { useRef } from "react";
import PlateSearch from "@cartbot/plate-search";

function App() {
  const plateSearchRef = useRef();

  return (
    <>
      <button onClick={() => plateSearchRef.current?.open()}>
        Search by Registration
      </button>

      <PlateSearch
        ref={plateSearchRef}
        apiKey="YOUR_API_KEY"
        hideDefaultButton
        onModalClose={() => console.log("Modal closed")}
      />
    </>
  );
}

// Available methods:
// plateSearchRef.current.open()   - Open the modal
// plateSearchRef.current.close()  - Close the modal
// plateSearchRef.current.toggle() - Toggle modal state

Auto-Close on Vehicle Selection

By default, the component shows a confirmation/summary page after vehicle selection. To auto-close the modal immediately after selection:

<PlateSearch
  apiKey="YOUR_API_KEY"
  autoCloseOnSelect={true}
  onModalClose={() => {
    // Modal closed after vehicle selection
    const vehicle = JSON.parse(
      localStorage.getItem("partbot_selected_vehicle")
    );
    console.log("Selected:", vehicle);
  }}
/>

Listening to Events

The component dispatches DOM events you can listen to:

// Listen to modal close events
document.addEventListener("plate-search-modal-close", (e) => {
  console.log("Modal closed at", e.detail.timestamp);
});

// Listen to vehicle selection events
document.addEventListener("plate-search-change", (e) => {
  console.log("Vehicle selected:", e.detail.vehicle_ids);
});

Advanced Usage

If you need direct access to the component without Shadow DOM isolation (for example, to apply your own styling), you can import the raw component:

import { PlateSearchRaw } from "@cartbot/plate-search";
// Note: You'll need to handle styling yourself when using PlateSearchRaw

Web Component

<script src="https://unpkg.com/@cartbot/plate-search@latest/build/dist/js/plate-search.js"></script>

<plate-search
  data-api-key="YOUR_API_KEY"
  data-theme-color="#10b981"
  data-use-geolocation="true"
/>

Web Component - Customization

<!-- Custom action button label -->
<plate-search
  data-api-key="YOUR_API_KEY"
  data-products-url="/products"
  data-action-button-label="View Parts"
/>

<!-- Hide default button (trigger modal from your own button) -->
<button onclick="document.querySelector('plate-search').open()">
  Search by Rego
</button>
<plate-search data-api-key="YOUR_API_KEY" data-hide-default-button="true" />

<!-- Auto-close after vehicle selection -->
<plate-search data-api-key="YOUR_API_KEY" data-auto-close-on-select="true" />

<!-- Inline (embedded) mode -->
<plate-search data-api-key="YOUR_API_KEY" data-display-mode="inline" />

<!-- Demo mode (2 unique lookups/day per browser session) -->
<plate-search data-api-key="YOUR_API_KEY" data-demo-mode="true" />

<script>
  // Control modal programmatically
  const plateSearch = document.querySelector("plate-search");

  plateSearch.open(); // Open the modal
  plateSearch.close(); // Close the modal
  plateSearch.toggle(); // Toggle modal open/close

  // Listen to events
  document.addEventListener("plate-search-modal-close", (e) => {
    console.log("Modal closed at", e.detail.timestamp);
  });

  document.addEventListener("plate-search-change", (e) => {
    console.log("Vehicle selected:", e.detail.vehicle_ids);
  });
</script>

Development

Prerequisites

• Bun >= 1.0.0

Getting Started

# Install dependencies
bun install

# Start development server
bun dev

Scripts

| Command | Description | | -------------------- | ----------------------------------------- | | bun dev | Start Vite development server | | bun run build | Build library, demo site, and copy assets | | bun run build:lib | Build only the library (ES + UMD bundles) | | bun run build:site | Build only the demo site | | bun test | Run tests with Vitest | | bun run preview | Preview the built site locally | | bun run serve:dist | Serve the dist folder locally |

Build Output

After running bun run build, the following files are generated:

dist/
├── js/
│   ├── plate-search.js      # UMD bundle (for <script> tags)
│   └── plate-search.es.js   # ES module bundle (for imports)
├── css/
│   └── plate-search.css     # Compiled styles
└── index.d.ts               # TypeScript definitions

build/dist/                   # Legacy path (for backwards compatibility)
├── js/
│   └── plate-search.js
└── css/
    └── plate-search.css

Publishing

1. Bump the version (this updates package.json and creates a git tag):

   npm version patch  # for bug fixes (3.1.3 → 3.1.4)
   npm version minor  # for new features (3.1.3 → 3.2.0)
   npm version major  # for breaking changes (3.1.3 → 4.0.0)

2. Build the package:

   bun run build

3. Publish to npm:

   Note: ensure you are logged in to npm with npm login

   bun run release

4. Push the version commit and tag:

   git push && git push --tags

This publishes to npm as @cartbot/plate-search with public access.

Copyright (c) Partbot Software Pty Ltd

use.partbot.io