Vue Line Clamp 3

Common errors

• TypeError: app.use is not a function

  cause Attempting to use `app.use()` on a raw component instance or an object that is not a Vue application instance created by `createApp()`.
  fix Ensure `app` is a valid Vue application instance: `import { createApp } from 'vue'; const app = createApp(YourRootComponent); app.use(lineClamp);`

• The argument passed to the directive must be a number

  cause The directive argument (e.g., `:20` in `v-line-clamp:20`) for the line-height fallback is not a valid number.
  fix Provide a numeric value for the line-height argument, typically corresponding to your text's CSS `line-height` in pixels. Example: `<p v-line-clamp:18="3">`.

• Property 'v-line-clamp' does not exist on type 'VNodeProps' or similar TypeScript error for directive

  cause TypeScript might not recognize the globally registered directive without proper type augmentation, or the plugin was not registered correctly.
  fix Ensure the plugin is registered via `app.use(lineClamp)`. For TypeScript, you might need to augment Vue's `GlobalComponents` or `Directive` types in a `d.ts` file if the library doesn't provide it automatically.

Warnings

• breaking Migrating from the original `vue-line-clamp` (Vue 2) to `vue-line-clamp-3` (Vue 3) requires updating to the Vue 3 application setup (`createApp` and `app.use()`) as `Vue.use()` is no longer available. This is a fundamental change in Vue's plugin registration API.
  Fix: Rewrite plugin registration from `Vue.use(lineClamp)` to `import { createApp } from 'vue'; const app = createApp({}); app.use(lineClamp);`.
• gotcha The directive syntax `v-line-clamp:lineHeight="numberOfLines"` can be confusing. The argument after the colon (`:lineHeight`) *must* be a number representing the `line-height` in pixels, which is used for the fallback method in browsers not supporting `-webkit-line-clamp`. The bound value (`="numberOfLines"`) is the actual number of lines to clamp to.
  Fix: Ensure the argument after the colon is a numeric `line-height` (e.g., `v-line-clamp:20`) and the bound value is the desired `numberOfLines` (e.g., `= "2"`).
• gotcha The JavaScript fallback method, used for browsers that do not support `-webkit-line-clamp`, does not display an ellipsis (`...`) at the end of the truncated text. This is a known limitation because the fallback cannot reliably control the specific part of the text node to clamp.
  Fix: Be aware of this visual difference in older/unsupported browsers. Consider providing alternative styling or custom fallback logic via the `fallbackFunc` plugin option if ellipsis is critical for all environments.
• gotcha There may be potential inconsistencies or problems when loading custom fonts. While tests have not revealed issues, custom font rendering and measurement can sometimes interfere with the directive's height calculations, particularly for the JavaScript fallback.
  Fix: Test thoroughly with custom fonts. If issues arise, consider adjusting `line-height` values, or providing a custom `fallbackFunc` with more robust measurement techniques, or opening an issue with a reproduction.

Install

• npm install vue-line-clamp-3 npm
• yarn add vue-line-clamp-3 yarn
• pnpm add vue-line-clamp-3 pnpm

Imports

• lineClamp
  wrong:

  const lineClamp = require('vue-line-clamp-3')

  correct:

  import lineClamp from 'vue-line-clamp-3'

  The directive is exported as a default export and intended for use with `app.use()` in Vue 3 applications, which primarily use ESM.
• Vue application setup
  wrong:

  Vue.use(lineClamp)

  correct:

  import { createApp } from 'vue';
  const app = createApp({});
  app.use(lineClamp);

  Vue 3 removed the global `Vue` constructor. Applications are created via `createApp`, and plugins are installed using the `app.use()` instance method.
• v-line-clamp directive usage

  <p v-line-clamp:lineHeight="numberOfLines">Long text...</p>

  The directive expects a numeric argument for `lineHeight` (used for fallback) and a numeric value for `numberOfLines`. Example: `<p v-line-clamp:20="2">`

Quickstart

This quickstart demonstrates how to install and register the `vue-line-clamp-3` directive, then apply it to multiple `<p>` elements in a Vue 3 component. It shows the `v-line-clamp:lineHeight="numberOfLines"` syntax, highlighting its role in controlling text truncation and cross-browser fallbacks.

import { createApp } from 'vue';
import lineClamp from 'vue-line-clamp-3';

const App = {
  template: `
    <div id="app" style="max-width: 400px; margin: 20px auto; border: 1px solid #eee; padding: 15px;">
      <h2>Vue Line Clamp 3 Example</h2>
      <p v-line-clamp:20="2" style="font-family: sans-serif; font-size: 16px; line-height: 20px; color: #333;">
        This is a very long piece of text that needs to be truncated to exactly two lines. If the browser
        supports '-webkit-line-clamp', it will use that for truncation and add an ellipsis. Otherwise,
        a fallback method using a calculated maximum height based on the provided line-height of 20px
        will be applied to clamp the text. This demonstrates the basic usage of the v-line-clamp directive
        to manage multi-line text overflow across different browser environments.
      </p>
      <br/>
      <p v-line-clamp:18="3" style="font-family: sans-serif; font-size: 14px; line-height: 18px; color: #555;">
        Here's another example with a different line count and line height to show its flexibility.
        The directive will adapt to these values to ensure the text is truncated correctly.
        Remember that the argument after the colon (e.g., :18) specifies the line-height for the fallback mechanism,
        and the value (e.g., ="3") specifies the desired number of lines.
      </p>
    </div>
  `
};

const app = createApp(App);

app.use(lineClamp, {
  // Optional: Set to true to import styles into <head> automatically.
  // importCss: true,
  // Optional: Customize the text-overflow property for modern browsers.
  // textOverflow: '...', 
  // Optional: Provide a custom fallback function for unsupported browsers.
  // fallbackFunc: (element, bindings, lines) => { /* custom logic */ }
});

app.mount('#app');