@samryansoftware/realestate-react

A React library for integrating with the SR Dreams Real Estate API. This library provides context providers, hooks, and reusable components for building real estate websites.

Installation

npm install @samryansoftware/realestate-react

Quick Start

1. Wrap your app with the context provider

import { SRDContextProvider } from '@samryansoftware/realestate-react';

function App() {
  return (
    <SRDContextProvider config={{ realtorId: '123abc' }}>
      <YourApp />
    </SRDContextProvider>
  );
}

2. Use the components and hooks

import { 
  RealtorProfile, 
  PropertyList, 
  useRealtor, 
  useProperties 
} from '@samryansoftware/realestate-react';

function RealtorPage() {
  const { realtor, loading } = useRealtor();
  const { properties } = useProperties();

  return (
    <div>
      <RealtorProfile />
      <PropertyList showPagination={true} />
    </div>
  );
}

API Reference

SRDContextProvider

The main context provider that manages API state and data fetching.

<SRDContextProvider config={config}>
  {children}
</SRDContextProvider>

Config Options

• realtorId (string): The realtor ID to fetch data for
• baseUrl (string, optional): Custom API base URL (defaults to https://realestateapi.srdreams.com/api/public)

Hooks

useSRD()

Returns the full context with all state and actions.

const { realtor, properties, loading, error, fetchRealtor, fetchProperties } = useSRD();

useRealtor()

Returns realtor-specific data and actions.

const { realtor, loading, error, fetchRealtor, clearError } = useRealtor();

useProperties()

Returns properties-specific data and actions.

const { properties, propertiesLoading, propertiesError, pagination, fetchProperties } = useProperties();

useProperty(propertyId)

Returns data for a specific property.

const { property, loading, error, refetch } = useProperty('property123');

Components

RealtorProfile

Displays realtor information with avatar and contact details.

<RealtorProfile 
  showAvatar={true}
  showContact={true}
  showStats={false}
  className="custom-class"
/>

RealtorAvatar

Displays just the realtor's avatar.

<RealtorAvatar 
  size="medium" // 'small' | 'medium' | 'large'
  className="custom-class"
/>

RealtorContact

Displays contact information with clickable email and phone links.

<RealtorContact 
  showEmail={true}
  showPhone={true}
  className="custom-class"
/>

PropertyList

Displays a list of properties with filtering and pagination.

<PropertyList 
  filters={{ status: 'active', minPrice: 200000 }}
  layout="grid" // 'grid' | 'list'
  showPagination={true}
  itemsPerPage={12}
  onPropertyClick={(property) => console.log(property)}
  renderProperty={(property) => <CustomPropertyCard property={property} />}
/>

PropertyCard

Displays a single property card.

<PropertyCard 
  property={property}
  showImages={true}
  showDetails={true}
  showRealtor={false}
  className="custom-class"
/>

PropertyFilter

Provides filtering controls for properties.

<PropertyFilter 
  onFiltersChange={(filters) => console.log(filters)}
  currentFilters={{ status: 'active' }}
  className="custom-class"
/>

PropertyPagination

Displays pagination controls.

<PropertyPagination 
  pagination={pagination}
  currentPage={currentPage}
  onPageChange={setCurrentPage}
  className="custom-class"
/>

Standalone API Functions

For use outside of React components:

import { srdAPI } from '@srdreams/realestate-react';

// Get realtor
const realtor = await srdAPI.getRealtor('123abc');

// Get properties with filters
const properties = await srdAPI.getProperties('123abc', {
  status: 'active',
  minPrice: 200000,
  maxPrice: 500000,
  sort: 'price:asc'
});

// Get specific property
const property = await srdAPI.getProperty('property123');

// Get all realtors
const realtors = await srdAPI.getAllRealtors({
  search: 'john',
  sort: 'name:asc'
});

Filter Options

Property Filters

• status: 'active' | 'pending' | 'sold'
• type: 'house' | 'apartment' | 'condo' | 'townhouse' | 'land'
• minPrice: number
• maxPrice: number
• search: string (searches title, description, address)
• sort: string (format: 'field:direction')
• page: number
• limit: number

Sort Options

• price:asc - Price low to high
• price:desc - Price high to low
• createdAt:desc - Newest first
• createdAt:asc - Oldest first
• title:asc - Title A-Z

Examples

Complete Realtor Website

import { 
  SRDContextProvider, 
  RealtorProfile, 
  PropertyList, 
  PropertyFilter 
} from '@samryansoftware/realestate-react';

function RealtorWebsite() {
  const [filters, setFilters] = useState({});

  return (
    <SRDContextProvider config={{ realtorId: '123abc' }}>
      <div>
        <header>
          <RealtorProfile showStats={true} />
        </header>
        
        <main>
          <PropertyFilter onFiltersChange={setFilters} />
          <PropertyList 
            filters={filters}
            showPagination={true}
            onPropertyClick={(property) => {
              window.location.href = `/property/${property._id}`;
            }}
          />
        </main>
      </div>
    </SRDContextProvider>
  );
}

Property Detail Page

import { SRDContextProvider, useProperty } from '@samryansoftware/realestate-react';

function PropertyDetail({ propertyId }) {
  return (
    <SRDContextProvider config={{ realtorId: '123abc' }}>
      <PropertyDetailContent propertyId={propertyId} />
    </SRDContextProvider>
  );
}

function PropertyDetailContent({ propertyId }) {
  const { property, loading, error } = useProperty(propertyId);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!property) return <div>Property not found</div>;

  return (
    <div>
      <h1>{property.title}</h1>
      <p>${property.price.toLocaleString()}</p>
      <p>{property.address}</p>
      <p>{property.description}</p>
      
      <div>
        {property.images.map((image, index) => (
          <img key={index} src={image.url} alt={image.alt} />
        ))}
      </div>
    </div>
  );
}

Styling

The library uses CSS classes with the srd- prefix. You can override styles by targeting these classes:

.srd-realtor-profile {
  /* Custom styles */
}

.srd-property-card {
  /* Custom styles */
}

.srd-pagination {
  /* Custom styles */
}

Error Handling

All components and hooks include error handling:

const { error, clearError } = useRealtor();

if (error) {
  return (
    <div>
      <p>Error: {error}</p>
      <button onClick={clearError}>Try Again</button>
    </div>
  );
}

TypeScript Support

The library is fully typed with TypeScript. All interfaces are exported:

import { Realtor, Property, PropertyFilters } from '@samryansoftware/realestate-react';

interface MyComponentProps {
  realtor: Realtor;
  filters: PropertyFilters;
}

License

MIT