Installation

Open in ChatGPT

Getting started with UI blocks is quick and straightforward. Below you’ll find multiple installation methods to choose from. Select the package manager that matches your project setup, follow each step carefully, and you’ll be ready to use our components in no time.

Using UI blocks CLI

To streamline the installation process, we provide a command-line interface (CLI) tool that automates the setup for you. Simply run the following command in your terminal:

pnpm dlx hybrid-astro-ui@latest init

npx hybrid-astro-ui@latest init

yarn dlx hybrid-astro-ui@latest init

bunx hybrid-astro-ui@latest init

Add new components

Now you can start using UI blocks components in your project right away!

pnpm dlx hybrid-astro-ui@latest add button

npx hybrid-astro-ui@latest add button

yarn dlx hybrid-astro-ui@latest add button

bunx hybrid-astro-ui@latest add button

Manual Installation

If you prefer to install UI blocks manually, follow these steps based on your package manager of choice:

Step 1: Install Dependencies

pnpm add @lucide/astro tailwind-merge clsx && pnpm astro add tailwind

npm install @lucide/astro tailwind-merge clsx && npm astro add tailwind

yarn add @lucide/astro tailwind-merge clsx && yarn astro add tailwind

bun add @lucide/astro tailwind-merge clsx && bun astro add tailwind

After installing the dependencies, make sure to configure Tailwind CSS in your Astro project if you haven’t done so already. You can refer to the Astro documentation for detailed instructions on setting up Tailwind CSS.

Step 2: Prepare global.css

Next, ensure that your global.css file includes the necessary Tailwind directives. Add the following lines to your src/styles/global.css file:

/* src/styles/global.css */

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

:root {
  --background: oklch(99% 0.005 280);
  --foreground: oklch(18% 0.015 280);

  --primary: oklch(52% 0.18 250);
  --primary-foreground: oklch(99% 0.005 250);

  --secondary: oklch(98% 0.006 259.931);
  --secondary-foreground: oklch(22% 0.02 260);

  --muted: oklch(95% 0.008 270);
  --muted-foreground: oklch(50% 0.015 270);

  --accent: oklch(94% 0.025 200);
  --accent-foreground: oklch(20% 0.03 200);

  --border: oklch(90% 0.008 270);
  --input: oklch(92% 0.008 270);
  --ring: oklch(52% 0.18 250);

  --radius: 0.625rem;
}

.dark {
  --background: oklch(13% 0.01 280);
  --foreground: oklch(96% 0.008 280);

  --primary: oklch(68% 0.19 250);
  --primary-foreground: oklch(13% 0.01 250);

  --secondary: oklch(22% 0.015 260);
  --secondary-foreground: oklch(96% 0.01 260);

  --muted: oklch(20% 0.012 270);
  --muted-foreground: oklch(60% 0.015 270);

  --accent: oklch(25% 0.03 200);
  --accent-foreground: oklch(96% 0.01 200);

  --border: oklch(28% 0.015 270);
  --input: oklch(26% 0.015 270);
  --ring: oklch(68% 0.19 250);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);

  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);

  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);

  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);

  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);

  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);

  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

@layer base {
  * {
    @apply border-border;
  }
  body {
    @apply bg-background text-foreground;
  }
}

Import this global.css file in any layout or page where you use UI blocks components. We recommend adding it to a shared layout to ensure consistent styling across your site.

---
// Example code

import '@/src/styles/global.css';
---

<!doctype html>
<html lang="en" class="dark">
	<head></head>

	<body class="w-full min-h-screen flex flex-col items-center justify-center">
		<slot />
	</body>
</html>

Step 3: Configure tsconfig.json

Add the paths configuration in compilerOptions to use the @/ alias:

// tsconfig.json

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
  
}

Step 4: Create Utility Functions

Before using the helper function shown below, create a new folder named lib in the root of your project. Inside that folder, add a file called utils.ts and paste the following code into it:

// ./lib/utils.ts

import { twMerge } from "tailwind-merge";
import { clsx, type ClassValue } from "clsx";

export function cls(...args: ClassValue[]) {
  return twMerge(clsx(args))
}

import type { PaginateFunction } from 'astro';
import { getCollection, type CollectionEntry } from 'astro:content';

import type { collections } from '@/src/content/config';
type CollectionName = keyof typeof collections;

interface PaginationOptions {
    pageSize?: number;
    sortByFn?: ((a: CollectionEntry<CollectionName>, b: CollectionEntry<CollectionName>) => number);
    filterFn?: (post: CollectionEntry<CollectionName>) => boolean;
    collection: CollectionName
}


export function createCollectionPagination(options: PaginationOptions) {
    const {
        pageSize = 10,
        sortByFn ,
        filterFn,
        collection
    } = options;

    return async ({ paginate }: { paginate: PaginateFunction }) => {
        let items = await getCollection(collection);

        if (filterFn) {
            items = items.filter(filterFn);
        }

        if (sortByFn) {
            items = items.sort(sortByFn);
        } 

        return paginate(items, { pageSize });
    };
}

Step 5: Add declaration

This declaration is necessary because TypeScript does not understand .astro files by default. By defining a module for the .astro extension and typing it as an AstroComponentFactory, we allow TypeScript to recognize Astro components as valid imports inside .ts files. This improves the developer experience by enabling IntelliSense, preventing type errors, and making it possible to modularize and reuse Astro components naturally within TypeScript code, which is essential for building tools, CLIs, and advanced component architectures.

/// <reference types="astro/client" />

declare module '*.astro' {
  import type { AstroComponentFactory } from 'astro';
  const component: AstroComponentFactory;
  export default component;
}

Step 6: Add new components