DOCSEARCHbyAlgolia
Submit Docs

HextaUI

repository·master·Indexed 20 days ago

https://github.com/preetsuthar17/hextaui

A UI library and framework featuring a registry of components and blocks. It includes tools for managing block metadata, theme application (supporting themes like retro-blue, purple, and night-wind), and integration with the shadcn CLI for component installation. The library provides utility functions for filtering catalogs, retrieving component metadata, and managing CSS class merging via a cn() utility.

Tokens
3K
Snippets
16
Records
20
Agent score
71%

What's inside hexta-ui

  1. Set up HextaUI for local development

    master

    To start developing locally, ensure corepack is enabled, install dependencies using pnpm, and run the development server. If port 3000 is already in use by another application, you can run the dev server on port 3001.

    Note: Running pnpm dev automatically builds the local shadcn registry. The resulting files in public/r/*.json are build artifacts and should not be committed to version control.

    corepack enable
pnpm install --frozen-lockfile
pnpm dev -- -p 3001

  2. Verify and build HextaUI

    master

    Use the following commands to ensure the project integrity and prepare it for production:

    • pnpm verify: Runs a comprehensive check including the registry, TypeScript, ESLint, formatting, and tests.
    • pnpm build: Executes the production build process.
    pnpm verify
pnpm build

  4. Install HextaUI components via shadcn CLI

    master

    HextaUI components can be added to your project using the shadcn CLI. Use the pnpm dlx shadcn@latest add command followed by the specific component package name in the format @hextaui/[component-id]. Replace [component-id] with the identifier of the component you wish to install.

    pnpm dlx shadcn@latest add @hextaui/component-id

  5. Configure next-sitemap settings

    master

    The next-sitemap.config.js file defines the configuration for the next-sitemap package used in this project. It controls the base URL for the generated sitemaps and whether a robots.txt file is automatically generated.

    Available configuration keys:

    • siteUrl: The base URL for your site. It defaults to https://hextaui.com but can be overridden using the SITE_URL environment variable.
    • generateRobotsTxt: A boolean indicating whether to generate a robots.txt file. Set to true to enable generation.
    /** @type {import('next-sitemap').IConfig} */
module.exports = {
  siteUrl: process.env.SITE_URL || "https://hextaui.com",
  generateRobotsTxt: true,
};

  6. Merge class names with cn()

    master

    The cn utility function is used to conditionally merge CSS class names. It combines the functionality of clsx (for conditional logic) and tailwind-merge (to resolve Tailwind CSS class conflicts). This is the standard way to handle dynamic class names in HextaUI components to ensure that the last class provided always takes precedence in Tailwind's utility engine.

    import { cn } from "./lib/utils";

// Example usage:
const classes = cn("px-2 py-1", isError && "bg-red-500", "px-4");
// Result: "py-1 bg-red-500 px-4" (px-4 overrides px-2 via twMerge)

  7. Get theme-specific radius

    master

    Use getThemeRadius(themeName: ThemeName, isDark: boolean) to retrieve the specific border-radius string for a given theme and mode. This is useful if you need to manually apply radius values outside of the applyTheme flow.

    import { getThemeRadius } from './lib/themes';

const radius = getThemeRadius('orbiter', false); // Returns "0rem"

  8. Retrieve block metadata with getBlockMetaById

    master

    Use getBlockMetaById to find the metadata for a specific block using its unique id. This returns a BlockMeta object containing the block's title, description, category, and its corresponding React component (Demo). If no block matches the provided ID, it returns undefined.

    import { getBlockMetaById } from '@/lib/blocks-registry';

const block = getBlockMetaById('button-primary');

if (block) {
  console.log(block.title);
  const DemoComponent = block.Demo;
  // Render <DemoComponent />
}

  9. Retrieve items from the HextaUI catalog

    master

    The catalog contains all registry items, including components and blocks. You can retrieve specific items by their unique name using getCatalogItem(id). This is useful for programmatic access to registry metadata, documentation links, or API references associated with a specific UI element.

    import { getCatalogItem } from '@/lib/catalog';

const item = getCatalogItem('my-component-id');
if (item) {
  console.log(item.name, item.categories);
}

  10. Apply a theme to the document

    master

    Use the applyTheme function to inject theme CSS variables and border radius into the document root (<html>). This function handles both light and dark mode variations.

    Note on Border Radius: If the user is not using a Chrome-based browser, the --radius variable is automatically set to 0.625rem to ensure consistent rendering across different browser engines.

    import { themes, applyTheme } from './lib/themes';

const myTheme = themes.find(t => t.name === 'purple');
if (myTheme) {
  // Apply the purple theme in dark mode
  applyTheme(myTheme, true);
}

  11. Identify the block category of a catalog item

    master

    For items categorized as blocks, you can determine their specific functional category (e.g., ai, auth, billing) using getBlockCategory(item). This function looks at the second element in the item's categories array and validates it against the supported BlockCategory list.

    import { getBlockCategory, getCatalogItem } from '@/lib/catalog';

const item = getCatalogItem('auth-login-block');
if (item) {
  const category = getBlockCategory(item);
  console.log(category); // e.g., 'auth'
}

  12. Filter and access components and blocks catalogs

    master

    HextaUI provides two pre-filtered catalogs for easier access to specific types of registry items:

    • componentsCatalog: A sorted list of all items where the primary category is component.
    • blocksCatalog: A list of all items where the primary category is block.

    Items in these catalogs follow the CatalogItem structure, which extends the base registry item with categories, optional docs, and optional meta (containing apiRef).