Customizing Components

Overview

Astro Portfolio v3 includes a collection of reusable components organized into different categories. This guide will help you understand and customize these components to match your needs.

Component Organization

Components are organized in the following structure:

src/components/
├── home/          # Homepage-specific components
├── navs/          # Navigation components
├── shared/        # Reusable shared components
└── ui/            # UI elements and icons

Shared Components

These are the most commonly customized components that appear throughout the site.

SectionHeader
ArticleCard
ThemeSwitcher

A reusable section header component with title and subtitle.

Props

string

required

The main heading text

string

required

The description text below the heading

'primary' | 'secondary'

default:"'primary'"

The color of the accent bar

Usage

---
import { SectionHeader } from '@/components/shared';
---

<SectionHeader 
  title="About Me" 
  subtitle="Learn more about my journey"
  accentColor="secondary"
/>

Customization Example

Modify src/components/shared/SectionHeader.astro to change the layout:

<div class='mb-16 space-y-3'>
  <div class='flex items-center gap-3'>
    <!-- Change accent from bar to dot -->
    <div class={`h-3 w-3 bg-${accentColor} rounded-full`}></div>
    <h2 class='text-3xl md:text-4xl font-bold'>
      {title}
    </h2>
  </div>
  <p class='text-muted-foreground md:text-lg pl-7'>
    {subtitle}
  </p>
</div>

Displays blog post information in a card format with hover effects.

Props

string

required

The blog post title

string

required

Brief description of the post

Date

required

Publication date

string[]

required

Array of tag strings

string

required

URL slug for the post

string

Optional cover image URL

Usage

---
import { ArticleCard } from '@/components/shared';
---

<ArticleCard
  title="Getting Started with Astro"
  description="Learn the basics of Astro framework"
  dateCreated={new Date('2024-03-05')}
  tags={['astro', 'web-dev']}
  slug="getting-started-with-astro"
  cover_image="/images/astro-cover.jpg"
/>

Customization Example

Add a reading time indicator:

src/components/shared/ArticleCard.astro

---
interface Props {
  // ... existing props
  readingTime?: number;
}

const { readingTime, /* ... other props */ } = Astro.props;
---

<div class='flex items-center justify-between'>
  <time class='text-sm' datetime={dateCreated.toISOString()}>
    {formattedDate}
  </time>
  {readingTime && (
    <span class='text-sm text-muted-foreground'>
      {readingTime} min read
    </span>
  )}
</div>

A button that cycles through light, dark, and retro themes.

Features

Cycles through three themes: light → dark → retro
Persists theme preference in localStorage
Respects system color scheme preference
Animated icon transitions

Usage

---
import ThemeSwitcher from '@/components/shared/ThemeSwitcher.astro';
---

<ThemeSwitcher />

Customization Example

Change to toggle between only light and dark:

const cycleTheme = () => {
  const themes: Theme[] = ['light', 'dark']; // Remove 'retro'
  const current = getTheme();
  const next = current === 'light' ? 'dark' : 'light';
  setTheme(next);
};

Navbar
Footer

The main navigation bar component at the top of the page.Location: src/components/navs/Navbar.astro

Customization Ideas

Add Navigation Links

<nav class="flex gap-6">
  <a href="/">Home</a>
  <a href="/blog">Blog</a>
  <a href="/projects">Projects</a>
  <!-- Add your custom link -->
  <a href="/services">Services</a>
</nav>

Change Logo Style

<a href="/" class="text-2xl font-bold">
  {siteConfig.name}
</a>

The footer component with copyright and links.Location: src/components/navs/Footer.astro

Customization Ideas

Add Social Links

<div class="flex gap-4">
  <a href="https://twitter.com/yourusername">Twitter</a>
  <a href="https://github.com/yourusername">GitHub</a>
  <a href="https://linkedin.com/in/yourusername">LinkedIn</a>
</div>

Add Newsletter Signup

<div class="max-w-md">
  <h3>Subscribe to Newsletter</h3>
  <NewsletterForm />
</div>

Home Page Components

Components specific to the homepage are located in src/components/home/.

component

Displays the main hero section text and call-to-actionFile: src/components/home/HeroText.astro

component

Shows the hero image with animationsFile: src/components/home/HeroImage.astro

component

The about section with your description and imageFile: src/components/home/About.astro

component

Displays your work experience timelineFile: src/components/home/WorkExperience.astro

component

Showcases your projects in a grid layoutFile: src/components/home/Projects.astro

component

Lists recent blog postsFile: src/components/home/Blogs.astro

Creating Custom Components

Follow these steps to create your own custom component:

Create the component file

Create a new .astro file in the appropriate directory:

touch src/components/shared/CustomBadge.astro

Define the component

src/components/shared/CustomBadge.astro

---
interface Props {
  label: string;
  variant?: 'primary' | 'secondary';
}

const { label, variant = 'primary' } = Astro.props;
---

<span 
  class:list={[
    'px-3 py-1 rounded-full text-sm font-medium',
    variant === 'primary' && 'bg-primary text-primary-foreground',
    variant === 'secondary' && 'bg-secondary text-secondary-foreground'
  ]}
>
  {label}
</span>

Export from index

Add to src/components/shared/index.ts:

export { default as CustomBadge } from './CustomBadge.astro';

Use in your pages

---
import { CustomBadge } from '@/components/shared';
---

<CustomBadge label="New" variant="primary" />

Component Best Practices

Keep components focused: Each component should have a single, well-defined purpose.

Use TypeScript interfaces: Always define prop types for better development experience.

Make components responsive: Use Tailwind’s responsive prefixes (sm:, md:, lg:) for mobile-first design.

When modifying components that use transition:name attributes, be careful not to create duplicate names, as this can break Astro’s view transitions.

Advanced Customizations

Adding Interactive Features

For components that need client-side interactivity, use Astro’s <script> tag:

<button id="my-button" class="btn">Click me</button>

<script>
  function handleClick() {
    console.log('Button clicked!');
  }
  
  const button = document.getElementById('my-button');
  button?.addEventListener('click', handleClick);
  
  // Re-initialize on page transitions
  document.addEventListener('astro:page-load', () => {
    const button = document.getElementById('my-button');
    button?.addEventListener('click', handleClick);
  });
</script>

Using Framework Components

Astro supports React, Vue, Svelte, and other frameworks. To use a React component:

---
import ReactCounter from '@/components/ReactCounter.tsx';
---

<!-- Make it interactive with client:load -->
<ReactCounter client:load initialCount={0} />

Component Examples Repository

Check out the existing components in the source code for more examples:

Glow effect: ArticleCard.astro:95-146
Theme detection: ThemeSwitcher.astro:46-82
Modal implementation: ShareModal.astro
Form handling: NewsletterForm.astro

Get Started

Core Features

Content Management

Customization

Deployment

Overview

Component Organization

Shared Components

Props

Usage

Customization Example

Props

Usage

Customization Example

Features

Usage

Customization Example

Navigation Components

Customization Ideas

Customization Ideas

Home Page Components

Creating Custom Components

Component Best Practices

Advanced Customizations

Adding Interactive Features

Using Framework Components

Component Examples Repository

​Overview

​Component Organization

​Shared Components

​Props

​Usage

​Customization Example

​Props

​Usage

​Customization Example

​Features

​Usage

​Customization Example

​Navigation Components

​Customization Ideas

​Customization Ideas

​Home Page Components

​Creating Custom Components

​Component Best Practices

​Advanced Customizations

​Adding Interactive Features

​Using Framework Components

​Component Examples Repository

Overview

Component Organization

Shared Components

Props

Usage

Customization Example

Props

Usage

Customization Example

Features

Usage

Customization Example

Navigation Components

Customization Ideas

Customization Ideas

Home Page Components

Creating Custom Components

Component Best Practices

Advanced Customizations

Adding Interactive Features

Using Framework Components

Component Examples Repository