Skip to main content

​
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.
A reusable section header component with title and subtitle.

​
Props

​
title
string
required
The main heading text
​
subtitle
string
required
The description text below the heading
​
accentColor
'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>

​
Home Page Components

Components specific to the homepage are located in src/components/home/.
​
HeroText
component
Displays the main hero section text and call-to-actionFile: src/components/home/HeroText.astro
​
HeroImage
component
Shows the hero image with animationsFile: src/components/home/HeroImage.astro
​
About
component
The about section with your description and imageFile: src/components/home/About.astro
​
WorkExperience
component
Displays your work experience timelineFile: src/components/home/WorkExperience.astro
​
Projects
component
Showcases your projects in a grid layoutFile: src/components/home/Projects.astro
​
Blogs
component
Lists recent blog postsFile: src/components/home/Blogs.astro

​
Creating Custom Components

Follow these steps to create your own custom component:
1

Create the component file

Create a new .astro file in the appropriate directory:
touch src/components/shared/CustomBadge.astro
2

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>
3

Export from index

Add to src/components/shared/index.ts:
export { default as CustomBadge } from './CustomBadge.astro';
4

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

Build docs developers (and LLMs) love

Get started for freeTalk to us