TypeScript Tutorial: Building a Simple Interactive Web-Based Image Gallery

Written by

learnmodernjavascript

in

In the digital age, images are an integral part of how we communicate and consume information. From showcasing products to sharing memories, images are powerful tools. However, displaying them effectively on the web requires more than just embedding an <img> tag. A well-designed image gallery enhances user experience, allowing for easy navigation, zooming, and a visually appealing presentation. This tutorial will guide you through building a simple, interactive image gallery using TypeScript, a language that brings structure, type safety, and maintainability to your JavaScript projects. We’ll explore the core concepts, step-by-step implementation, and address common pitfalls along the way. By the end, you’ll have a functional image gallery and a solid understanding of how to use TypeScript in a practical, real-world scenario.

Why TypeScript?

Before diving into the code, let’s address the elephant in the room: why TypeScript? While JavaScript is the language of the web, it has its shortcomings, particularly when it comes to large-scale projects. TypeScript addresses these issues by:

  • Adding Static Typing: TypeScript introduces static typing, allowing you to define the types of variables, function parameters, and return values. This helps catch errors early in development, preventing runtime surprises.
  • Improving Code Readability: With types, your code becomes more self-documenting, making it easier for you and others to understand and maintain.
  • Enhancing Developer Experience: TypeScript provides better autocompletion, refactoring, and error checking in your IDE, leading to increased productivity.
  • Supporting Modern JavaScript Features: TypeScript transpiles to JavaScript, so you can use the latest JavaScript features without worrying about browser compatibility.

In essence, TypeScript helps you write cleaner, more robust, and more maintainable JavaScript code. It’s a worthwhile investment for any developer looking to build professional-grade web applications.

Project Setup

Let’s set up our development environment. You’ll need:

  • Node.js and npm (or yarn): These are essential for managing dependencies and running TypeScript.
  • A Code Editor: Visual Studio Code, Sublime Text, or any editor that supports TypeScript.

First, create a new project directory and initialize it with npm:

mkdir image-gallery-ts
cd image-gallery-ts
npm init -y

Next, install TypeScript and a few other necessary packages:

npm install typescript --save-dev
npm install --save-dev @types/node
npm install --save-dev @types/dom

Explanation of the above commands:

  • npm install typescript --save-dev: Installs the TypeScript compiler as a development dependency.
  • npm install --save-dev @types/node: Installs type definitions for Node.js, which we may need later if we interact with the file system.
  • npm install --save-dev @types/dom: Installs type definitions for the DOM, essential for interacting with the browser.

Now, let’s create a tsconfig.json file in the root of your project. This file configures the TypeScript compiler. You can generate a basic one using the TypeScript compiler:

npx tsc --init --rootDir src --outDir dist --esModuleInterop --module commonjs

This command creates a tsconfig.json file with a lot of options. Here’s a simplified version that’s easier to understand:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "outDir": "dist",
    "rootDir": "src",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules"
  ]
}

Here’s what each option means:

  • target: Specifies the JavaScript version to compile to (e.g., “es5”, “es6”, “esnext”).
  • module: Specifies the module system to use (e.g., “commonjs”, “esnext”).
  • outDir: Specifies the output directory for compiled JavaScript files.
  • rootDir: Specifies the root directory of your TypeScript source files.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • strict: Enables strict type checking.
  • skipLibCheck: Skips type checking of declaration files (.d.ts).
  • include: Specifies the files to include in the compilation.
  • exclude: Specifies the files to exclude from the compilation.

Create a directory named src in your project root. This is where your TypeScript code will reside.

Coding the Image Gallery

Let’s start building the core functionality of our image gallery. We’ll begin with the HTML structure, then move on to the TypeScript code to make it interactive.

HTML Structure

Create an index.html file in the project root with the following structure:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Image Gallery</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="gallery-container">
        <div class="gallery-controls">
            <button id="prevBtn">&lt; Previous</button>
            <button id="nextBtn">Next &gt;</button>
        </div>
        <div class="gallery-image-container">
            <img id="galleryImage" src="" alt="">
        </div>
    </div>
    <script src="dist/index.js"></script>
</body>
</html>

This HTML provides the basic structure:

  • A container for the entire gallery (.gallery-container).
  • Controls for navigation (.gallery-controls) with “Previous” and “Next” buttons.
  • A container for the image (.gallery-image-container).
  • An <img> tag (#galleryImage) to display the current image.
  • A link to the stylesheet (style.css) for styling.
  • A script tag to include the compiled JavaScript (dist/index.js).

Create a basic style.css file in your project root to provide some styling to the gallery.

.gallery-container {
    width: 80%;
    margin: 20px auto;
    border: 1px solid #ccc;
    padding: 10px;
    text-align: center;
}

.gallery-controls {
    margin-bottom: 10px;
}

.gallery-image-container {
    max-width: 100%;
}

#galleryImage {
    max-width: 100%;
    height: auto;
}

TypeScript Code (src/index.ts)

Now, let’s write the TypeScript code that will handle the image display and navigation. Create a file named src/index.ts and add the following code:

// Define an interface for the image data
interface Image {
    src: string;
    alt: string;
}

// Array of image objects
const images: Image[] = [
    { src: "image1.jpg", alt: "Image 1" },
    { src: "image2.jpg", alt: "Image 2" },
    { src: "image3.jpg", alt: "Image 3" }
];

// Get references to HTML elements
const galleryImage = document.getElementById('galleryImage') as HTMLImageElement;
const prevBtn = document.getElementById('prevBtn') as HTMLButtonElement;
const nextBtn = document.getElementById('nextBtn') as HTMLButtonElement;

// Initialize the current image index
let currentImageIndex: number = 0;

// Function to update the image in the gallery
function updateImage(): void {
    galleryImage.src = images[currentImageIndex].src;
    galleryImage.alt = images[currentImageIndex].alt;
}

// Function to go to the previous image
function showPreviousImage(): void {
    currentImageIndex = (currentImageIndex - 1 + images.length) % images.length;
    updateImage();
}

// Function to go to the next image
function showNextImage(): void {
    currentImageIndex = (currentImageIndex + 1) % images.length;
    updateImage();
}

// Add event listeners to the buttons
prevBtn.addEventListener('click', showPreviousImage);
nextBtn.addEventListener('click', showNextImage);

// Initial image display
updateImage();

Let’s break down this code:

  • Interface Image: Defines the structure of our image data, with src (the image URL) and alt (the alternative text).
  • Array images: This array stores our image data. Replace the placeholder image paths with the actual paths to your images. Make sure you have images named image1.jpg, image2.jpg, and image3.jpg in your project, or change the image paths in the code.
  • HTML Element References: The code gets references to the <img> tag and the navigation buttons using document.getElementById(). The as HTMLImageElement and as HTMLButtonElement assertions tell TypeScript the type of the elements, allowing for type-safe access to their properties.
  • currentImageIndex: A variable to keep track of the currently displayed image.
  • updateImage() Function: This function updates the src and alt attributes of the <img> tag with the data from the images array based on the currentImageIndex.
  • showPreviousImage() and showNextImage() Functions: These functions handle the navigation logic. They update the currentImageIndex, ensuring it stays within the bounds of the images array using the modulo operator (%) to loop through the images.
  • Event Listeners: Event listeners are added to the “Previous” and “Next” buttons to call the respective navigation functions when clicked.
  • Initial Image Display: The updateImage() function is called initially to display the first image when the page loads.

Compiling and Running

To compile the TypeScript code, run the following command in your terminal:

tsc

This will compile your src/index.ts file into a dist/index.js file. Now, open the index.html file in your browser. You should see the first image from your images array, and you should be able to navigate through the images using the “Previous” and “Next” buttons. If the images do not appear, double-check the image paths in the images array and ensure that the images are in the correct location relative to your HTML file.

Adding Features: Enhancements and Advanced Functionality

Now that we have a basic image gallery, let’s enhance it with some additional features to improve user experience and add more advanced functionality. We’ll look at zooming, adding captions, and implementing a responsive design.

Image Zooming

Implementing a zoom feature allows users to get a closer look at the images. We can achieve this by changing the max-width and max-height of the image on click.

First, add some CSS to handle the zoomed state. Add these styles to your style.css file:

.zoomed {
    max-width: 100%;
    max-height: 80vh; /* Adjust as needed */
    cursor: zoom-out;
}

.gallery-image-container {
    overflow: hidden; /* Prevents the zoomed image from overflowing the container */
}

Next, add a click event listener to the image in your src/index.ts file. This listener will toggle the zoomed class:


// Add a click event listener to the image
galleryImage.addEventListener('click', () => {
    galleryImage.classList.toggle('zoomed');
});

Recompile your TypeScript code with tsc. When you click on an image, it should zoom in, and clicking again should zoom it out. The cursor: zoom-out style provides visual feedback to the user.

Adding Image Captions

Captions provide context and descriptions for the images. We can easily add captions by modifying our Image interface and adding a caption property, and then displaying the caption below the image.

First, update the Image interface in src/index.ts:


interface Image {
    src: string;
    alt: string;
    caption: string;
}

Next, update the images array to include captions. For example:


const images: Image[] = [
    { src: "image1.jpg", alt: "Image 1", caption: "A beautiful sunset" },
    { src: "image2.jpg", alt: "Image 2", caption: "A mountain landscape" },
    { src: "image3.jpg", alt: "Image 3", caption: "A close-up of a flower" }
];

Now, add a <p> element below the <img> tag in your index.html to display the caption:


<div class="gallery-image-container">
    <img id="galleryImage" src="" alt="">
    <p id="imageCaption"></p>
</div>

Finally, in src/index.ts, get a reference to the caption element and update it in the updateImage() function:


const imageCaption = document.getElementById('imageCaption') as HTMLParagraphElement;

function updateImage(): void {
    galleryImage.src = images[currentImageIndex].src;
    galleryImage.alt = images[currentImageIndex].alt;
    imageCaption.textContent = images[currentImageIndex].caption;
}

Recompile your TypeScript code with tsc. The captions should now be displayed below each image.

Implementing Responsive Design

Responsive design ensures that your gallery looks good on all devices, from desktops to mobile phones. We can achieve this using CSS media queries.

In your style.css file, add the following media query:


@media (max-width: 768px) {
    .gallery-container {
        width: 95%;
    }
}

This media query adjusts the width of the gallery container on smaller screens (less than 768px wide). You can add more media queries to further customize the gallery’s appearance for different screen sizes.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them when building a TypeScript image gallery:

  • Incorrect File Paths: Double-check that your image paths in the images array are correct relative to your index.html file.
  • Type Errors: TypeScript will catch type errors during compilation. Review the error messages in your terminal and ensure that your code adheres to the defined types. For example, if you get an error like, “Property ‘src’ does not exist on type ‘HTMLButtonElement’,” it indicates a problem with accessing a property on the wrong type of HTML element.
  • Incorrect Element References: Make sure you are correctly referencing the HTML elements using document.getElementById(). Typos in the ID or incorrect casting can cause errors.
  • Missing Image Files: Ensure that the image files (e.g., image1.jpg, image2.jpg) exist in the correct directory.
  • Compilation Errors: If you get compilation errors, carefully examine the error messages provided by the TypeScript compiler. They will usually point you to the line of code causing the problem. Make sure you have the correct imports and that your code is syntactically correct.
  • CSS Issues: If your gallery doesn’t look as expected, check your CSS for any styling conflicts or incorrect selectors. Use your browser’s developer tools to inspect the elements and see which styles are being applied.
  • Incorrect Event Listener Attachments: Make sure event listeners are attached correctly to the right elements.

SEO Best Practices

To ensure your image gallery ranks well in search results, follow these SEO best practices:

  • Use Descriptive Alt Text: The alt attribute of the <img> tag is crucial for SEO. Provide descriptive and relevant alt text for each image. This helps search engines understand the content of your images and improves accessibility.
  • Optimize Image File Names: Use descriptive file names for your images (e.g., “blue-mountain-landscape.jpg” instead of “img1.jpg”).
  • Optimize Image File Sizes: Compress your images to reduce file sizes without significantly impacting quality. This improves page load times, which is a ranking factor. Tools like TinyPNG or ImageOptim can help with this.
  • Use a Responsive Design: Ensure your gallery is responsive and looks good on all devices. This improves user experience and is a ranking factor.
  • Include Relevant Keywords: Naturally incorporate relevant keywords into your image captions, alt text, and surrounding text. Avoid keyword stuffing.
  • Create a Sitemap: Submit a sitemap to search engines to help them discover and index your images.
  • Use Structured Data (Schema Markup): Consider using schema markup to provide search engines with more information about your images and gallery.

Key Takeaways

This tutorial has walked you through building a simple, interactive image gallery using TypeScript. You’ve learned about:

  • The benefits of using TypeScript for web development.
  • Setting up a TypeScript project.
  • Creating the HTML structure for an image gallery.
  • Writing TypeScript code to display and navigate images.
  • Adding features like image zooming and captions.
  • Implementing responsive design.
  • Troubleshooting common issues.
  • SEO best practices for image galleries.

FAQ

Here are some frequently asked questions about building image galleries with TypeScript:

  1. Can I use different image formats? Yes, you can use any image format supported by web browsers (e.g., JPG, PNG, GIF, WebP).
  2. How do I add more images to the gallery? Simply add more image objects to the images array in your src/index.ts file.
  3. Can I load images from an external source (API)? Yes, you can fetch image data from an API using the fetch API or a library like Axios. Update the images array with the data from the API response.
  4. How do I handle errors when loading images? You can use a try-catch block to handle potential errors when loading images. You might also want to display an error message if an image fails to load.
  5. How can I improve performance? Consider using image optimization techniques (e.g., lazy loading, image compression) to improve performance. Also, consider using a framework like React or Vue.js for larger and more complex galleries.

The journey doesn’t end here. The image gallery you’ve built is a foundation upon which you can build more complex and feature-rich applications. You can extend this gallery by adding features like image filtering, lightbox functionality, or integrating it with a backend to store and manage images. The key is to keep experimenting, learning, and refining your skills. Embrace the power of TypeScript to create robust, maintainable, and visually appealing web experiences that captivate your users.

More posts