The theui-svelte is TheUI's component library for Svelte 5, built on top of TailwindCSS. It combines the strength of Svelte and the features of TailwindCSS to create a powerful tool that accelerates your development process.

1. Features

• Built with ARIA roles and WCAG compliance for better usability.
• Highly customizable
• Support LTR/RTL.
• Easy theming, branding, and dark/light mode control.
• Optimized for leveraging svelte's reactivity
• Includes smooth transitions and animations for better user experience.
• Fully typed for enhanced development
• Offers examples, and usage guides tailored for Svelte.

2. Components

Last but not least, here is the list of components available in the component library!

3. Installation Guide

To add the Svelte Components library to your project, you can do it in two ways:

1. Use the boilerplate from GitHub.
2. Manual installation from scratch.

3.1 Install using boilerplate from GitHub

To install the boilerplate template, open your terminal and use the following command, replacing my-app with your desired project name.

# Clone the project
git clone https://github.com/mbparvezme/theui-svelte-starter.git my-app

# Install node modules
npm i

# Run the application
npm run dev

3.2. Manually Install from Scratch

Easily add theui-svelte to your project via a GitHub boilerplate or manual installation. For manual setup:

• Install SvelteKit and TailwindCSS.
• Configure Tailwind by updating tailwind.config.cjs and importing theui-svelte/style in +layout.svelte.

a. Install Sveltekit with TailwindCSS

# Install Svelte
npx sv create my-app
cd my-app

# Install node modules
npm i

# Install theui-svelte
npm i theui-svelte

b. Configuration

To integrate theui-svelte with your project, update your TailwindCSS configuration file by adding the following:

• Include the path to theui-svelte components {"./node_modules/theui-svelte/**/*.{html,js,svelte,ts}"} in the content array.
• Add the preset presets: [require("theui-svelte/preset")] from theui-svelte.

const config = {
    content: [
        "./src/**/*.{html,js,svelte,ts}",
+       "./node_modules/theui-svelte/**/*.{html,js,svelte,ts}"
    ],
+   presets: [require("theui-svelte/preset")],
    darkMode: "class",
    theme: {
        extend: {}
    },
    plugins: []
};

And that's all. You are ready to start your awesome project now.

4. Colors System

The color system in TailwindCSS is a powerful tool for developers, and we've taken it a step further in our component library! By leveraging TailwindCSS, we've introduced additional custom color classes tailored for consistent branding. These new classes work just like Tailwind's native color classes but are specifically designed for branding and come with full support for shades. Using the built-in color system you can generate both shaded and non-shaded color classes.

4.1 Available Color Classes

Our component library provides a set of custom classes to make integrating these colors into your designs seamless and flexible. Below is the full list of available classes:

| CLASS | Shades | Default value | DESCRIPTION | | --------------------------------------|---------------------------------------|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------- | | .[T]-brand-primary-[S] | 50, 100-900, 950 | #E93E3A | Use this class to apply the primary brand color, e.g., .bg-brand-primary-500 for background or .text-brand-primary-500 for text. | | .text-on-brand-primary-[S] | 50, 100-900, 950 | #FFFFFF | A foreground color designed to complement .bg-brand-primary-500 as the background. | | .[T]-brand-secondary-[S] | 50, 100-900, 950 | #E8E838 | Apply the secondary brand color, e.g., .bg-brand-secondary-500 for background or .text-brand-secondary-500 for text. | | .text-on-brand-secondary-[S] | 50, 100-900, 950 | #2E2105 | A foreground color specifically for use with .bg-brand-secondary-500 as the background. | | .[T]-error-[S] | 50, 100-900, 950 | #E53935 | Represent errors in your components with these color classes. | | .[T]-info-[S] | 50, 100-900, 950 | #29B6F6 | Use this class for informational or neutral messages. | | .[T]-success-[S] | 50, 100-900, 950 | #00C853 | Ideal for success messages or positive states in your components. | | .[T]-warning-[S] | 50, 100-900, 950 | #FFC107 | Perfect for warning or caution-related messages. | | .bg-primary | N/A | Light: 250 250 250Dark: 10 10 20 | A static background color for primary elements, defined via CSS variables. | | .bg-secondary | N/A | Light: 238 238 238Dark: 30 30 40 | A static background color for secondary elements, defined via CSS variables. | | .bg-alt | N/A | Light: 10 10 20Dark: 250 250 250 | A static background color for alternative sections, defined via CSS variables. | | .text-default | N/A | Light: 33 33 33Dark: 245 245 245 | The default text color in our library, defined via CSS variables. | | .text-alt | N/A | Light: 189 189 189Dark: 245 245 245 | A static alternative text color, ideal for secondary content. | | .text-muted | N/A | Light: 117 117 117Dark: 175 175 175 | A muted text color for less prominent content. |

Legend [T] = Type (e.g., bg, text, border, fill, etc.) [S] = Shade (e.g., 50, 100-900, 950) Example: bg-brand-primary-500, text-on-brand-primary-500, bg-error-400

Managing Colors

• Modify Colors: Update shades or use CSS variables for light/dark modes.
• Add Colors: Use Tailwind's tw-color-shades or define new variables in your CSS.
• Remove Colors: Set unwanted colors to undefined in tailwind.config.ts.

4.2 Modify Existing Colors

TailwindCSS’s color system is enhanced for branding with support for shaded and non-shaded colors. Customize or add new colors via tailwind.config.ts for shades or directly edit CSS variables for non-shaded colors.

Shaded Colors

If you want to modify a color with shades (i.e brand-primary, brand-secondary etc.), you can do it in tailwind.config.ts. For example, to change the primary brand color to #001A6E and secondary brand color to #FFE893, the code is given below:

// Modify colors in tailwind.config.ts
import twShades from 'tw-color-shades';

export default {
  theme: {
    extend: {
      colors: {
        "brand-primary": twShades('#001A6E'),
        "brand-secondary": twShades('#FFE893')
      }
    }
  }
};

Non-shaded Colors

There are some colors like background colors, text colors etc. behave differently in light and dark mode! These colors are shadeless and cannot be handled in the way shown above. For these colors we have use CSS variables! You can modify directly in the CSS file. For example, to change the primary background color in light mode to rgb(253 247 244) and in dark mode to rgb(104 87 82) and default text color in light mode to rgb(42 51 53) and in dark mode to rgb(253 247 244), the code is given below:

/* Modify colors in app.css or app.postcss */
@layer base {
  :root {
    --ui-bg-primary: 253 247 244;
    --ui-text-default: 42 51 53;
  }
  :root.dark {
    --ui-bg-primary: 104 87 82;
    --ui-text-default: 253 247 244;
  }
}

Writing the color values in the format provided, such as "253 247 244," rather than the conventional RGB code like "rgb(253 247 244)" is essential because it aligns with TailwindCSS's methodology for applying opacity to colors.

4.3 Add New Color

Shaded Colors

If you want to add a new class for color with shades, you can do it in the tailwind.config.ts file. For example, let's say, you want to add a new class in the color system named brand-tertiary with the base value #009990. Just follow the below steps:

// Generate new colors in tailwind.config.ts
import twShades from 'tw-color-shades';

export default {
  theme: {
    extend: {
      colors: {
        "brand-tertiary": twShades('#009990')
      }
    }
  }
};

Now you can access this color with bg-brand-tertiary-500 or other shades like bg-brand-tertiary-100 or bg-brand-tertiary-800.

Non-shaded Colors

If you want to add a new color that behaves differently in light and dark mode and you do not need "shades" for this colors, you can do this in your CSS file and then generate colors in tailwind.config.ts. To add a new color bg-tertiary in the color system, you can follow the below process:

/* define colors in app.css or app.postcss */
@layer base {
  :root {
    --my-bg-tertiary: 233 237 234;
  }
  :root.dark {
    --my-bg-tertiary: 114 97 92;
  }
}

// Generate the colors in tailwind.config.ts
import twShades from 'tw-color-shades';

export default {
  theme: {
    extend: {
      backgroundColor: {
        tertiary: twShades("--my-bg-tertiary")
      }
    }
  }
};

4.4 Remove A Color

To remove a color follow the Tailwind CSS way, just set the color to undefined in the tailwind.config.ts.

// Remove colors in tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        "brand-secondary": undefined
      },
      backgroundColor: {
        secondary: undefined
      }
    }
  }
};

This will remove all the brand-secondary color classes and bg-secondary class from the application build!

The z-index

This library leverages z-index for stacking elements. Avoid modifying z-index values to prevent layout disruptions.

Z-index helps in managing the stacking order of elements and overlays, controlling their arrangement along the z-axis. It is not recommended to customize these values in the design, as doing so may disrupt the layout along the z-axis.

| COMPONENT/Property | CLASS/Selector | VALUE (Z-INDEX) | | ------------------ | ------------------------- | --------------- | | Dropdown | .dropdown .backdrop | 10 | | Dropdown | .dropdown-content | 11 | | Sticky positioned | .sticky, [class$=:sticky] | 20 | | Fixed positioned | .fixed, [class$=:fixed] | 30 | | Offcanvas | .offcanvas | 40 | | Modal | .modal | 50 | | Popup | .popup | 60 | | Tooltip | .tooltip | 70 | | Notifications | .notifications | 80 |

Contributions

Prior to commencing work on new features or bug fixes, kindly inform us. If you wish to propose a new feature, please create a feature request in Github Issues. This promotes open discussions and avoids redundant efforts. It encompasses tasks like adding new components, introducing utility features, and making major changes to existing work.

Copyright

The code and documentation are copyright 2023 by M B Parvez, Gosoft and The UI.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Special Thanks To Gosoft.io and BIPBY Digital for being our digital partner