geonative-ui

Shadcn based components library and Tailwind CSS V4

Section

• Sidebar

Getting Started

Prerequisites

• Node.js 18+ (recommended)
• yarn

Documentation

• Vue 3 with Composition API
• TypeScript
• VueJS + Vite
• Shadcn Vue
• Tailwind CSS v4

Installation

yarn install

Running the Demo

To start the demo development server:

yarn dev:demo

Building the Demo

To build the demo for production:

yarn build:demo

The built files will be in the demo-dist directory.

Adding New Component Demos

To add a new component demo:

1. Create a new Vue file in the demo/src/views directory
2. Add the component to the routes in demo/src/routes.ts

Example route entry:

createRoute({
  path: '/your-component',
  name: 'your-component',
  component: () => import('./views/YourComponent.vue'),
  meta: {
    menuLabel: 'Your Component',
  },
});

Path Aliases

The demo uses the following path aliases:

• @geonative/ui/* - Points to the main /src directory (component library)
• @/* - Points to the /demo/src directory (demo application or your project using the library)

Example:

// Import from the component library
import { Button } from '@geonative/ui';

// Import from the demo application
import DemoLayout from '@/components/DemoLayout.vue';

Theme Management

The library includes a theme management system with built-in support for multiple themes and color modes (light/dark). The theme system is integrated with Tailwind CSS and uses CSS variables to apply theme settings.

Theme Composable

The useTheme composable provides functionality to manage themes:

import { useTheme } from '@geonative/ui/composables';

// Get theme state and functions
const {
  currentTheme, // Current selected theme name (reactive)
  currentThemeMode, // Current theme mode (light/dark) (reactive)
  selectedThemeMode, // User selected theme mode (light/dark/system) (reactive)
  availableThemes, // List of available themes (reactive)
  initializeThemes, // Initialize themes with configuration
  applyTheme, // Apply a theme by name
  setThemeMode, // Set theme mode (light/dark/system)
  resetTheme, // Reset to default theme
  getThemeConfig, // Get theme configuration
} = useTheme();

Initializing Themes

Initialize themes in your main app component:

import { useTheme } from '@geonative/ui/composables';
import initialThemes from '@/assets/themes/themes.json';
import type { ThemesData } from '@geonative/ui/types';

// Import the useTheme composable
const { initializeThemes } = useTheme();

// Initialize themes with the data from the JSON file
initializeThemes(initialThemes as ThemesData);

Theme Components

The library provides ready-to-use components for theme switching:

• ThemeSwitcher - Dropdown to select a theme
• ThemeModeSwitcher - Toggle between light/dark/system modes
• Theme - Link to apply a specific theme

<template>
  <ThemeSwitcher />
  <ThemeModeSwitcher />
  <Theme name="blue" />
</template>

<script setup lang="ts">
import { ThemeSwitcher, ThemeModeSwitcher, Theme } from '@geonative/ui/components';
</script>

Theme Structure

Theme configurations are organized as follows:

interface ThemesData {
  [themeName: string]: {
    light: ThemeConfig;
    dark: ThemeConfig;
  };
}

interface ThemeConfig {
  background: string; // Background color for the theme
  foreground: string; // Foreground color for text
  primary: string; // Primary background color
  'primary-foreground': string; // Primary foreground color
  secondary?: string; // Secondary background color
  'secondary-foreground'?: string; // Secondary foreground color
  card?: string; // Card background color
  'card-foreground'?: string; // Card foreground color
  popover?: string; // Popover background color
  'popover-foreground'?: string; // Popover foreground color
  muted?: string; // Muted background color
  'muted-foreground'?: string; // Muted foreground color
  accent?: string; // Accent background color
  'accent-foreground'?: string; // Accent color foreground
  destructive?: string; // Destructive action color background
  'destructive-foreground'?: string; // Destructive action color foreground
  border?: string; // Border color
  input?: string; // Input field background color
  ring?: string; // Ring color
  radius?: string; // Border radius
  [key: string]: string | undefined; // Allow additional custom properties
}

Icon System

The library provides a versatile icon system supporting multiple icon sources :

• SVG icons (from src/assets/icons directory of library and src/assets/icons directory of your project)
• Lucide icons
• Heroicons

Icon Component

The Icon component allows you to use different icon types:

<template>
  <Icon name="user" source="heroicons" type="solid" class="size-5 text-blue-500" />
</template>

<script setup lang="ts">
import { Icon } from '@geonative/ui/components';
</script>

Supported Icon Sources

The Icon component supports the following sources:

• svg: Custom SVG icons from assets directory

  <Icon name="antenna" source="svg" class="size-5 text-blue-500" />

• lucide: Icons from Lucide icon library

  <Icon name="AlertCircle" source="lucide" class="size-5 text-red-500" />

• heroicons: Icons from Heroicons (with type support: "solid" or "outline")

  <Icon name="bell" source="heroicons" type="solid" class="size-5 text-yellow-500" />
  <Icon name="bell" source="heroicons" type="outline" class="size-5 text-green-500" />

• avatar: Avatar component as an icon

  <Icon
    name="user"
    source="avatar"
    :avatar-props="{
      url: user.avatar,
      initials: user.name.slice(0, 2),
      class: 'bg-red-500',
    }"
  />

File Naming Conventions

For SVG icons, the name parameter corresponds to the file path in the assets directory:

• Simple name: antenna -> assets/icons/antenna.svg
• Path with underscore: battery_batt-level-2 -> assets/icons/battery/batt-level-2.svg
• Path with multiple levels: alert_actions_push-notification -> assets/icons/alert/actions/push-notification.svg

Action Component

The Action component provides a unified way to handle different types of actions like URLs, internal routes, or function calls.

Basic Usage

<template>
  <Action action-click="/about">
    <span>Go to About</span>
  </Action>
</template>

<script setup lang="ts">
import { Action } from '@geonative/ui/components';
</script>

Action Types

The actionClick prop accepts different types of values:

• Internal route: String that doesn't start with http:// or https://

  <Action action-click="/dashboard">Internal Link</Action>

• External URL: String starting with http:// or https://

  <Action action-click="https://github.com">External Link</Action>

• Function: Callback function to execute

  <Action :action-click="() => alert('Action triggered!')">
    <Button>Click Me</Button>
  </Action>

Combining with Other Components

Action is designed to wrap other components:

<Action action-click="/profile">
  <Button>Go to Profile</Button>
</Action>

<Action action-click="https://github.com" class="flex gap-1">
  <span>GitHub</span>
  <Icon name="arrow-top-right-on-square" source="heroicons" type="solid" class="size-4" />
</Action>

Drawer

The Drawer component provides a flexible and customizable drawer layout that can be used for side navigation, modals, or any off-canvas content.

Basic Usage

<template>
  <Drawer>
    <template #trigger>
      <Button>Drawer</Button>
    </template>

    <template #title>
      <span>Title</span>
    </template>

    <template #description>
      <span>Description</span>
    </template>

    <span>Content</span>

    <template #footer>
      <span>Footer</span>
    </template>
  </Drawer>
</template>

Drawer Props

Prop	Type	Default	Description
direction	'top' | 'bottom' | 'left' | 'right'	'right'	Position d'ouverture du drawer.
dismissible	boolean	true	Permet de fermer le drawer en cliquant à l'extérieur ou via Escape.

Drawer Slots

Slot	Description
trigger	Slot for the drawer trigger button.
title	Slot for custom title content.
description	Slot for custom description content.
default	Slot for main drawer content.
footer	Slot for custom footer content.

Sidebar

The Sidebar component provides a collapsible sidebar layout with support for multiple sections and items.

Includes Sidebar, SidebarNav, SidebarGroup, SidebarInset, SidebarTrigger, and SidebarProvider for building a flexible navigation sidebar.

Basic Usage

<template>
  <SidebarProvider>
    <Sidebar>
      <template #header>
        <span>Header</span>
      </template>

      <SidebarNav />

      <template #footer>
        <span>Footer</span>
      </template>
    </Sidebar>
  </SidebarProvider>
</template>

<script setup lang="ts">
import { SidebarProvider, Sidebar, SidebarNav } from '@geonative/ui/components';
</script>

Sidebar Props

Prop	Type	Default	Description
side	'left' | 'right'	'left'	Which side of the screen the sidebar appears.
variant	'sidebar' | 'floating' | 'inset'	'sidebar'	Display style of the sidebar.
collapsible	'offcanvas' | 'icon' | 'none'	'offcanvas'	Collapse behavior for responsiveness.
class	string	—	Additional Tailwind classes for styling.

Sidebar Slots

Slot	Description
header	Slot for custom header content.
default	Slot for main sidebar content.
footer	Slot for custom footer content.