Mirrors/tabler
1
0 Fork 0
mirror of https://github.com/tabler/tabler.git synced 2026-10-12 13:17:00 +04:00
Code Issues Projects Releases Wiki Activity
Files
dev
tabler/docs/content/ui/getting-started/upgrade/1-5.mdx
T

348 lines
17 KiB
Plaintext
Raw Permalink Blame History

---
title: Upgrade to 1.5
summary: Move a project from Tabler 1.4 to 1.5. Every breaking change is listed with a before and after example for markup, JavaScript and Sass.
description: Upgrade guide from Tabler 1.4 to 1.5 with all breaking changes, renamed classes and Sass updates.
added-in: '1.5.0'
order: 2
related: [/ui/getting-started/rtl]
---
Most projects only use the compiled CSS and JavaScript from `dist/`. If that is you, the upgrade is short: update the package, remove Bootstrap, and check the [color mode default](#color-mode-defaults-to-auto) and the [visual changes](#visual-changes). Projects that compile Tabler from the Sass sources have more work to do - see [Sass changes](#sass-changes).
## Overview
Use this table to find the changes that affect you.
If you…|You need to…
---|---
Load `dist/css` and `dist/js`|Remove Bootstrap's CSS and JS - Tabler now ships them
Load `bootstrap.bundle.min.js`|Remove it, or components will start twice
Use `window.bootstrap.Modal`|Use `window.tabler.Modal`
Compile `scss/tabler.scss` yourself|Switch to `@use … with ()` and add the PostCSS prefix step
Override Sass variables|Check the [list of removed variables](#removed-sass-variables)
Use `.badges-list` or `.tags-list`|Rename to `.badge-list` and `.tag-list` (old names still work)
Use ApexCharts|Update to ApexCharts 7
Use Turbo with Tabler|The built-in integration is gone - see [Turbo](#turbo-integration-removed)
Load `tabler-theme.js`|Pages follow the OS color scheme now - see [Color mode](#color-mode-defaults-to-auto)
Use payment provider icons|Check the [removed providers](#removed-payment-providers)
Link files inside `dist/libs`|Check the [moved paths](#smaller-distlibs-folder)
Load `tabler.rtl.css`|You can drop it - plain `tabler.css` now handles RTL
Have `.text-gray-*` classes in your markup|They color the text now - see [Gray text utilities](#gray-text-utilities)
## Update the package
Install the new version:
```sh
npm install --save @tabler/core@1.5.0
```
Or update the CDN links:
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@tabler/core@1.5.0/dist/css/tabler.min.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@tabler/core@1.5.0/dist/js/tabler.min.js"></script>
```
## Bootstrap is now part of Tabler
Bootstrap is no longer a dependency. Its JavaScript and Sass sources live inside `@tabler/core`, based on Bootstrap 5.3.8.
Remove Bootstrap from your project:
```sh
npm uninstall bootstrap
```
Then remove the separate Bootstrap files from your pages:
```diff
- <link rel="stylesheet" href="/vendor/bootstrap/bootstrap.min.css" />
<link rel="stylesheet" href="/vendor/tabler/tabler.min.css" />
- <script src="/vendor/bootstrap/bootstrap.bundle.min.js"></script>
<script src="/vendor/tabler/tabler.min.js"></script>
```
If you leave `bootstrap.bundle.min.js` on the page, every component starts twice. You will see modals that close at once, or dropdowns that never open.
### JavaScript imports
Bootstrap components are exported from `@tabler/core`:
```diff
- import { Modal, Tooltip } from 'bootstrap'
+ import { Modal, Tooltip } from '@tabler/core'
```
The sources under `js/` are TypeScript now: `js/tabler.js` became `js/tabler.ts` and `js/src/*.js` became `js/src/*.ts`. Import from the package root or from `dist/js/`, not from the source files.
### Global variable
The UMD build puts everything under `tabler`:
```diff
- const modal = new bootstrap.Modal(element)
+ const modal = new tabler.Modal(element)
```
`tabler.bootstrap.Modal` also works. You can replace `bootstrap.` with `tabler.bootstrap.` across your project as a quick fix.
### Data attributes
Every component now reads `data-tblr-*` as well as `data-bs-*`. Both prefixes work, so you do not need to change your markup:
```html
<button data-bs-toggle="modal" data-bs-target="#modal">Works</button>
<button data-tblr-toggle="modal" data-tblr-target="#modal">Also works</button>
```
Dark mode still uses `data-bs-theme="dark"`.
## Turbo integration removed
The built-in `@hotwired/turbo` integration is gone, together with the `.turbo-progress-bar` styles. You can keep using Turbo, but install it yourself and style the progress bar in your own CSS:
```css
.turbo-progress-bar {
height: 3px;
background-color: var(--tblr-primary);
}
```
## Color mode defaults to auto
`tabler-theme.js` used `light` as its default color mode. It now defaults to `auto`: with no stored choice, the script reads `prefers-color-scheme` and sets `data-bs-theme` on `<html>` to `light` or `dark`. Visitors whose operating system is set to dark will see your pages in dark mode after the upgrade.
To keep light as the starting point, render the attribute on the server; the script only replaces it with a stored choice or a URL parameter:
```html
<html data-bs-theme="light">
```
A visitor can still pick a mode with `?theme=light` or `?theme=dark` in the URL, and the choice is stored in `localStorage`. See [Color modes](/ui/getting-started/color-modes) for all theme settings.
## Removed payment providers
The payment icons now come from the [Tabler Payments](/payments) set, which adds 74 providers and drops 12 that no longer operate. Their `.payment-provider-*` classes and `dist/img/payments/*.svg` files are gone:
`clickandbuy`, `dotpay`, `laser`, `ogone`, `okpay`, `paymill`, `payza`, `sage`, `solo`, `switch`, `ukash`, `verisign`
If you still show one of them, copy its SVG from the 1.4 package into your project.
## Smaller dist/libs folder
`dist/libs` now holds only the runtime files each library needs, instead of a full copy of every package. If you link straight to a file inside `dist/libs`, check that the path still exists after the upgrade. These are the paths most likely to break:
Removed|Use instead
---|---
`tom-select/dist/js/tom-select.complete.min.js`|`tom-select/dist/js/tom-select.base.min.js`
`tom-select/dist/css/tom-select.min.css`|`tom-select/dist/css/tom-select.bootstrap5.min.css`
`countup.js/dist/countUp.min.js`|`countup.js/dist/countUp.umd.js`
`signature_pad/dist/signature_pad.min.js`|`signature_pad/dist/signature_pad.umd.min.js`
`star-rating.js/dist/star-rating.esm.min.js`|`star-rating.js/dist/star-rating.min.js`
`plyr/dist/plyr.polyfilled.min.js`|`plyr/dist/plyr.min.js`
`litepicker/dist/bundle.js`|`litepicker/dist/litepicker.js`
`jsvectormap/dist/jsvectormap.min.css`|`jsvectormap/dist/jsvectormap.css`
`@hotwired/turbo/`|Install `@hotwired/turbo` yourself, see [Turbo](#turbo-integration-removed)
The base build of Tom Select ships without plugins, so load any plugin you use from npm. The unminified builds are gone as well, such as `apexcharts/dist/apexcharts.js` or `clipboard/dist/clipboard.js`: link the `.min.js` file next to them. Anything else that is no longer shipped can be loaded from your own `node_modules` or from a CDN. The list of shipped files is in [libs.json](https://github.com/tabler/tabler/blob/dev/core/libs.json).
## Sass changes
Skip this section if you use the compiled CSS from `dist/css`.
### Sass module system
The Sass sources now use the module system (`@use` and `@forward`). Setting variables before an `@import` no longer changes them. Use `@use … with ()` instead:
```diff
- $primary: #f11d46;
- $font-family-sans-serif: 'Inter', sans-serif;
- @import '@tabler/core/scss/tabler';
+ @use '@tabler/core/scss/tabler' with (
+ $primary: #f11d46,
+ $font-family-sans-serif: ('Inter', sans-serif)
+ );
```
<Warning title="`@import` is on its way out">
It still compiles, but Dart Sass marks it as deprecated and will remove it in Sass 3.0. Move to `@use` now.
</Warning>
### Custom property prefix moved to PostCSS
The `$prefix` Sass variable was removed. Custom properties are written without a prefix in the sources, such as `--card-bg`, and the public `--tblr-` prefix is added at build time by PostCSS.
This means plain `sass` output no longer holds `--tblr-*` names:
```css
/* sass scss/tabler.scss → tabler.css */
:root {
--primary: #066fd1; /* not --tblr-primary */
}
```
Add [postcss-prefix-custom-properties](https://www.npmjs.com/package/postcss-prefix-custom-properties) to your CSS pipeline, after Sass:
```js
import postcss from 'postcss'
import prefixCustomProperties from 'postcss-prefix-custom-properties'
const result = await postcss([
prefixCustomProperties({
prefix: 'tblr-',
// Vendor stylesheets read their own variable names - never prefix these
ignore: [/^--tblr-/, /^--bs-/, /^--fc-/, /^--gl-/, /^--litepicker-/, /^--plyr-/, /^--ts-/, '--section-bg'],
}),
]).process(css, { from: undefined })
```
If you do not want a PostCSS step, use the compiled `dist/css/tabler.css` and override the CSS variables. See [Customize Tabler](/ui/getting-started/customize).
### Custom properties instead of Sass variables
Some Sass variables only fed a CSS variable, so they were dropped in favor of that variable. Surface colors are the most common case:
```diff
- @use '@tabler/core/scss/tabler' with ($bg-surface: #fff);
+ :root {
+ --tblr-bg-surface: #fff;
+ }
```
### Removed Sass variables
Unused `!default` variables were removed. Passing one to `@use … with ()` now raises a Sass error instead of being ignored:
```text
Error: This variable was not declared with !default in the @used module.
```
These variables are gone:
`$accordion-bg`, `$accordion-border-color`, `$accordion-button-active-bg`, `$accordion-button-focus-border-color`, `$accordion-color`, `$accordion-icon-width`, `$avatar-box-shadow`, `$badge-line-height`, `$bg-surface`, `$bg-surface-dark`, `$bg-surface-secondary`, `$bg-surface-tertiary`, `$card-bg-hover`, `$card-hover-box-shadow`, `$code-line-height`, `$enable-social-colors`, `$font-local`, `$font-size-75`, `$font-size-100`, `$font-size-200`, `$font-size-300`, `$font-size-400`, `$font-size-500`, `$font-size-600`, `$font-size-700`, `$font-weight-black`, `$form-check-input-checked-color`, `$form-switch-bg-size`, `$line-height-100`, `$line-height-200`, `$line-height-300`, `$line-height-400`, `$line-height-500`, `$line-height-600`, `$line-height-700`, `$nav-link-active-color`, `$nav-tabs-bg`, `$navbar-brand-margin-right`, `$navbar-dark-active-bg`, `$prefix`, `$spacer-0`, `$steps-margin`, `$table-bg-scale-dark`, `$table-th-border-color`, `$table-th-color`, `$text-muted`, `$text-secondary-dark-opacity`, `$text-secondary-light-opacity`
Most of them have a CSS variable you can use instead. For example, `$font-size-300` is now `--tblr-font-size-h3`, and `$text-muted` is `--tblr-secondary-color`.
### Removed Sass files
Bootstrap compiles from `scss/bootstrap/` now, so the partials that used to bridge it are gone: `_bootstrap-config.scss`, `_bootstrap-components.scss` and `_bootstrap-override.scss`. `_debug.scss`, `_variables-marketing.scss` and `vendor/_turbo.scss` were removed too; the marketing variables now live next to their components in `marketing/`. Import the entry points rather than the partials:
```scss
@use '@tabler/core/scss/tabler';
@use '@tabler/core/scss/tabler-marketing';
```
### Google Fonts variables
`$font-google` and `$font-google-monospaced` still add the Google Fonts `@import`, but they no longer put the font at the front of `$font-family-sans-serif` and `$font-family-monospace`. `$font-local` is gone. Set the font stack yourself:
```diff
@use "@tabler/core/scss/tabler" with (
$font-google: "Inter",
+ $font-family-sans-serif: ("Inter", -apple-system, BlinkMacSystemFont, sans-serif)
);
```
Tabler no longer ships a web font. The default stack uses the system font of the device, so nothing is downloaded. To use your own font, override `--tblr-font-sans-serif`.
## Renamed classes
The old names still work, so you can rename at your own pace.
Old|New|Status
---|---|---
`.badges-list`|`.badge-list`|Deprecated alias
`.tags-list`|`.tag-list`|Deprecated alias
`.markdown`|`.prose`|Both supported
```diff
- <div class="badges-list">
+ <div class="badge-list">
```
## Visual changes
These changes are not breaking, but they change how a page looks. Check your screens after the upgrade.
- **Fonts**: the defaults are now the system fonts of the device, instead of Inter. To keep your old stack, set `--tblr-font-sans-serif`.
- **Shadows**: the `--tblr-shadow-*` tokens use a new `xs` to `2xl` scale, plus `overlay`, with softer defaults.
- **Colors**: body text is lighter, dark mode borders and disabled inputs are easier to see, and `--tblr-gray-*-fg` tokens now map straight to `--tblr-gray-*`.
- **Links**: in dark mode, links use a lighter tint of the primary color, so they meet the 4.5:1 contrast ratio on dark surfaces. Override `--tblr-link-color` to change it.
- **Sizes**: `.form-control`, `.btn` and `.input-group` now agree on `sm` and `lg` sizes, `.btn-icon` is square, and `.icon-sm` uses a `1.5` stroke width.
- **Cards**: `--tblr-card-header-bg` and `--tblr-card-footer-bg` can be set on their own, and the card status bar is `3px`.
- **Layout**: the `margin-inline-start: calc(100vw - 100%)` hack on the root element is gone, so there is no white gap on the left when a scrollbar is present.
- **Trending**: the component uses the `arrow-up` and `arrow-down` icons instead of `trending-up` and `trending-down`.
### Gray text utilities
Tabler 1.4 had no `.text-gray-*` classes, only `.text-gray-*-fg`. A class like `.text-gray-200` in your markup did nothing, and the text kept the color of its parent. Tabler 1.5 adds `.text-gray-50` to `.text-gray-950`, so the same class now sets the color. On `.text-gray-200` that is a very light gray, which is hard to read on a white page.
Pick the shade you want to see, or remove the class:
```diff
- <p class="text-gray-200">Last updated 3 hours ago</p>
+ <p class="text-gray-600">Last updated 3 hours ago</p>
```
For muted text, `.text-secondary` follows the theme and keeps enough contrast in dark mode.
## RTL
The Sass sources use logical properties and a `--tblr-dir` multiplier, so plain `tabler.css` works in both directions. Set `dir` on the document and drop the RTL stylesheet:
```diff
<html dir="rtl">
- <link rel="stylesheet" href="/dist/css/tabler.rtl.min.css" />
+ <link rel="stylesheet" href="/dist/css/tabler.min.css" />
```
The `*.rtl.css` files are still published, so nothing breaks if you keep them. See the [RTL support](/ui/getting-started/rtl) page for the full list of RTL builds and which utilities flip automatically.
## Third party libraries
- **ApexCharts** moved from 3.54 to 7.0. If you install ApexCharts yourself, update it too and read the [ApexCharts changelog](https://github.com/apexcharts/apexcharts.js/releases) - the major versions renamed several options. Charts also read `--chart-{id}-color-{index}` variables now.
- **Tabler Icons** moved to 3.46, and **Tabler Illustrations** to 1.16.
- **Tom Select** cannot be compiled from its Sass sources against Tabler anymore. Its `tom-select.bootstrap5.scss` reads Bootstrap variables such as `$border-color` and passes them to `color.adjust()`, but in Tabler these are now CSS variables like `var(--gray-200)`, which is not a color to Sass. Use the compiled `tom-select.bootstrap5.css` instead, or set the two variables Tom Select adjusts to plain colors before importing it:
```scss
// `as *` keeps Tabler's variables visible to the @import below
@use '@tabler/core/scss/tabler' as *;
$select-color-text: #182433;
$select-color-item-border: #e6e7e9;
@import 'tom-select/dist/scss/tom-select.bootstrap5';
```
## Browser support
Tabler 1.5 relies on `light-dark()`, `color-mix()`, `@property` and `:has()` with no fallback. This raises the minimum browser versions:
Browser|Minimum version
---|---
Chrome|123
Edge|123
Firefox|128
Safari|17.5
iOS Safari|17.5
Older browsers still render the layout, but colors fall back to unstyled values. See [Browser support](/ui/getting-started/browser-support) for the full list.
## What is new in 1.5
Besides the changes above, 1.5 adds:
- New components: `.btn-ghost`, `.card-gradient`, progress steps, progress background, `.progress-lg` and `.progress-xl`, background pattern utilities, `.text-gray-*` utilities, and a `.bg-blur` utility.
- A folded sidebar (`navbar-folded`, `navbar-folded-hover`) with `nav-section-title` labels and a `navbar-footer` zone.
- An `auto` color mode that follows the system `prefers-color-scheme` setting.
- Print styles: `d-print-*` utilities and a `media-print` mixin, see [Printing](/ui/utilities/printing).
- A language selector in the navbar and a new structure for the `navbar-side` component.
- New preview pages: CRM dashboard, crypto dashboard, task list, onboarding, pay, card gradients, all elements, and several new modals.
- [Framework integration guides](/ui/getting-started/frameworks) for Laravel, React, Next.js, Vue, Angular, Nuxt, Symfony, Django, Rails, SvelteKit and Astro.
The full list is in the [changelog](https://github.com/tabler/tabler/blob/dev/core/CHANGELOG.md).
Reference in new issue View Git Blame Copy Permalink