TypeScript Tutorial: Creating a Simple Web-Based Image Gallery

Written by

learnmodernjavascript

in

In today’s digital world, images are everywhere. From social media to e-commerce, websites are heavily reliant on visual content. Creating a user-friendly and efficient image gallery is a common task for web developers. This tutorial will guide you through building a simple, yet functional, web-based image gallery using TypeScript. We’ll cover everything from setting up your project to displaying images and handling user interactions. This project is ideal for beginners and intermediate developers looking to enhance their skills in TypeScript and front-end development.

Why TypeScript for an Image Gallery?

TypeScript offers several advantages that make it a great choice for this project:

  • Type Safety: TypeScript’s static typing helps catch errors early in the development process, reducing debugging time and improving code reliability.
  • Code Maintainability: Types make your code easier to understand and maintain, especially as the project grows.
  • Improved Developer Experience: Features like autocompletion and refactoring tools enhance productivity and code quality.
  • Modern JavaScript: TypeScript compiles to JavaScript, ensuring compatibility with all modern browsers.

Project Setup

Before we start coding, let’s set up our project. We’ll use npm (Node Package Manager) and a simple HTML file to get things rolling. Make sure you have Node.js and npm installed on your system.

1. Create a Project Directory

Open your terminal or command prompt and create a new directory for your project:

mkdir image-gallery-ts
cd image-gallery-ts

2. Initialize npm

Initialize a new npm project. This will create a package.json file to manage our dependencies.

npm init -y

3. Install TypeScript

Install TypeScript as a development dependency:

npm install --save-dev typescript

4. Create a tsconfig.json file

Create a tsconfig.json file to configure the TypeScript compiler. You can generate a basic one using the TypeScript compiler itself:

npx tsc --init

This command creates a tsconfig.json file with default settings. You can customize these settings to fit your needs. For example, you might want to specify the output directory for compiled JavaScript files.

5. Create HTML and TypeScript Files

Create two files in your project directory:

  • index.html: This file will contain the HTML structure of your image gallery.
  • index.ts: This file will contain the TypeScript code for your image gallery.

HTML Structure (index.html)

Let’s create the basic HTML structure for our image gallery. This will include a container for the images and potentially some navigation controls.

<!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="image-container">
            <img id="galleryImage" src="" alt="">
        </div>
        <div class="navigation">
            <button id="prevButton">< Previous</button>
            <button id="nextButton">Next ></button>
        </div>
    </div>
    <script src="index.js"></script>
</body>
</html>

This HTML provides a basic structure. We have a container for the images, an image element to display the current image, and navigation buttons for moving between images. We’ve also included a link to a style.css file, which we’ll create later for styling and a link to our compiled Javascript file, index.js.

CSS Styling (style.css)

Let’s add some basic CSS styling to make the image gallery look presentable. Create a file named style.css in the same directory as your HTML file. Add the following CSS:

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

.image-container {
    margin-bottom: 10px;
}

img {
    max-width: 100%;
    max-height: 400px;
}

.navigation {
    display: flex;
    justify-content: space-between;
    margin-top: 10px;
}

button {
    padding: 10px 20px;
    background-color: #4CAF50;
    color: white;
    border: none;
    cursor: pointer;
}

TypeScript Code (index.ts)

Now, let’s write the TypeScript code that will handle the image display and navigation. This is where the magic happens!


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

// Sample image data
const images: Image[] = [
    { url: 'image1.jpg', alt: 'Image 1' },
    { url: 'image2.jpg', alt: 'Image 2' },
    { url: 'image3.jpg', alt: 'Image 3' },
    // Add more images here
];

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

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

// Function to update the image display
function updateImage(): void {
    if (galleryImage) {
        galleryImage.src = images[currentImageIndex].url;
        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();
}

// Event listeners for the navigation buttons
if (prevButton) {
    prevButton.addEventListener('click', showPreviousImage);
}

if (nextButton) {
    nextButton.addEventListener('click', showNextImage);
}

// Initial image display
updateImage();

Let’s break down this code:

1. Image Interface

We define an Image interface to represent the structure of our image data. This is good practice for type safety.

interface Image {
    url: string;
    alt: string;
}

2. Image Data

We create an array of Image objects. Replace the placeholder image URLs with the actual paths to your images, or place images in the same directory as your HTML.

const images: Image[] = [
    { url: 'image1.jpg', alt: 'Image 1' },
    { url: 'image2.jpg', alt: 'Image 2' },
    { url: 'image3.jpg', alt: 'Image 3' },
    // Add more images here
];

3. HTML Element References

We get references to the HTML elements we need to manipulate: the image element and the navigation buttons. The as HTMLImageElement and as HTMLButtonElement assertions tell TypeScript what type of elements these are, enabling type-safe access to their properties and methods.

const galleryImage = document.getElementById('galleryImage') as HTMLImageElement;
const prevButton = document.getElementById('prevButton') as HTMLButtonElement;
const nextButton = document.getElementById('nextButton') as HTMLButtonElement;

4. Current Image Index

We initialize a variable to keep track of the currently displayed image index.

let currentImageIndex = 0;

5. Update Image Function

This function updates the src and alt attributes of the image element to display the current image based on the currentImageIndex.

function updateImage(): void {
    if (galleryImage) {
        galleryImage.src = images[currentImageIndex].url;
        galleryImage.alt = images[currentImageIndex].alt;
    }
}

6. Navigation Functions

These functions handle the navigation logic. They update the currentImageIndex and call updateImage() to display the new image. The modulo operator (%) ensures that the index wraps around to the beginning or end of the image array.

function showPreviousImage(): void {
    currentImageIndex = (currentImageIndex - 1 + images.length) % images.length;
    updateImage();
}

function showNextImage(): void {
    currentImageIndex = (currentImageIndex + 1) % images.length;
    updateImage();
}

7. Event Listeners

We add event listeners to the navigation buttons to call the appropriate navigation functions when the buttons are clicked.

if (prevButton) {
    prevButton.addEventListener('click', showPreviousImage);
}

if (nextButton) {
    nextButton.addEventListener('click', showNextImage);
}

8. Initial Image Display

Finally, we call updateImage() to display the first image when the page loads.

updateImage();

Compiling and Running the Code

Now that we have our HTML, CSS, and TypeScript code, let’s compile the TypeScript code into JavaScript and run the application.

1. Compile TypeScript

Open your terminal and run the TypeScript compiler. This will create a index.js file in your project directory.

npx tsc

2. Open in Browser

Open the index.html file in your web browser. You should see the first image from your image array, along with the navigation buttons. Click the buttons to navigate through the images.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

1. Incorrect Image Paths

Mistake: The images are not displaying because the image paths in the images array are incorrect.

Fix: Double-check the image paths in your index.ts file. Make sure the paths are relative to your index.html file. You can use absolute paths, but relative paths are generally preferred for portability.

2. Element Not Found

Mistake: You get an error like “Cannot read properties of null (reading ‘src’)” or “Cannot read properties of null (reading ‘addEventListener’)”.

Fix: This usually means that the HTML elements you are trying to access (e.g., galleryImage, prevButton, nextButton) are not found. Make sure the id attributes in your HTML match the element references in your TypeScript code. Also, ensure that the script tag that loads the JavaScript file is placed after the HTML elements that it references.

3. Type Errors

Mistake: TypeScript is showing type errors in your code.

Fix: Read the error messages carefully. They will guide you to the source of the problem. Ensure that your code adheres to the types defined in your interfaces and variables. Use type assertions (e.g., as HTMLImageElement) when necessary to help TypeScript understand the types of your elements.

4. Button Functionality Not Working

Mistake: The navigation buttons don’t do anything.

Fix: Check that the event listeners are correctly attached to the buttons. Verify that the functions showPreviousImage() and showNextImage() are correctly implemented and that the currentImageIndex is being updated properly. Use console.log() statements within the functions to debug.

Enhancements and Next Steps

This is a basic image gallery. Here are some ideas for enhancements:

  • Error Handling: Add error handling to gracefully handle cases where images fail to load.
  • Loading Indicators: Show a loading indicator while images are loading.
  • Responsiveness: Make the gallery responsive so it looks good on different screen sizes.
  • Image Zoom/Lightbox: Implement a feature to zoom in on images or display them in a lightbox.
  • Image Preloading: Preload images to improve the user experience.
  • Dynamic Image Loading: Fetch images from an API or a database.
  • Add Captions: Add image captions to provide more context.
  • Keyboard Navigation: Implement keyboard navigation (e.g., left and right arrow keys).

Key Takeaways

  • TypeScript enhances code quality and maintainability.
  • Interfaces define the structure of your data.
  • Event listeners handle user interactions.
  • The modulo operator is useful for cycling through arrays.
  • Debugging is an essential part of the development process.

FAQ

1. Can I use this code with different image formats?

Yes, the code is compatible with most common image formats (JPEG, PNG, GIF, etc.). Just make sure the file extensions in your image paths match the actual file types.

2. How do I add more images to the gallery?

Simply add more objects to the images array in your index.ts file. Each object should have a url and an alt property.

3. How can I deploy this image gallery to a website?

You can deploy the files to a web server. You’ll need to upload the index.html, index.js (the compiled JavaScript file), style.css, and your image files to your web server. Most web hosting providers offer file management tools to help with this process. You may also need to configure your web server to serve the files correctly.

4. How can I style the gallery differently?

Modify the CSS in the style.css file to change the appearance of the gallery. You can change colors, fonts, layout, and more. Experiment with different CSS properties to achieve your desired look.

Conclusion

Building an image gallery is a fundamental project that provides a great opportunity to learn and practice TypeScript and front-end development skills. By following this tutorial, you’ve created a functional image gallery, and you’ve learned about the benefits of using TypeScript, the importance of type safety, and how to handle user interactions. Remember to experiment with the code, add your own images, and explore the enhancements to further your understanding and create a more sophisticated image gallery. The knowledge gained here can be applied to many other web development projects. Keep coding, keep learning, and keep building!

More posts