From 82db5901921dd2438e61cdf12a8213854f4af4f0 Mon Sep 17 00:00:00 2001 From: Eric Fennis Date: Mon, 12 Jun 2023 22:10:15 +0200 Subject: [PATCH] General improvements in documentation (#1348) * General improvements in documentation * fix typo * Update lucide-angular.md * Fix build * remove duplicated key --------- Co-authored-by: Karsa --- docs/.vitepress/lib/icons.ts | 10 +- .../components/home/HomeIconCustomizer.vue | 2 +- docs/guide/installation.md | 134 ++++++++++++------ docs/guide/packages/lucide-angular.md | 18 ++- docs/guide/packages/lucide-preact.md | 60 +++++--- docs/guide/packages/lucide-react-native.md | 54 ++++--- docs/guide/packages/lucide-react.md | 60 +++++--- docs/guide/packages/lucide-solid.md | 63 +++++--- docs/guide/packages/lucide-static.md | 18 ++- docs/guide/packages/lucide-svelte.md | 51 ++++--- docs/guide/packages/lucide-vue-next.md | 72 ++++++---- docs/guide/packages/lucide-vue.md | 54 ++++--- docs/guide/packages/lucide.md | 38 +++-- docs/vercel.json | 2 +- icons/circle-slash-2.json | 1 - 15 files changed, 405 insertions(+), 232 deletions(-) diff --git a/docs/.vitepress/lib/icons.ts b/docs/.vitepress/lib/icons.ts index 14dd7c1..ac1c6c9 100644 --- a/docs/.vitepress/lib/icons.ts +++ b/docs/.vitepress/lib/icons.ts @@ -8,14 +8,6 @@ const DATE_OF_FORK = '2020-06-08T16:39:52+0100'; const directory = path.join(process.cwd(), "../icons"); -export function getAllNames() { - const fileNames = fs.readdirSync(directory).filter((file) => path.extname(file) === '.json'); - - return fileNames - .filter((fileName) => fs.existsSync(directory + '/' + path.basename(fileName, '.json') + '.svg')) - .map((fileName) => path.basename(fileName, '.json')); -} - export interface GetDataOptions { withChildKeys?: boolean } @@ -49,7 +41,7 @@ export async function getData(name: string) { } export async function getAllData(): Promise<{ name: string, iconNode: IconNodeWithKeys}[]> { - const names = getAllNames(); + const names = Object.keys(iconNodes); return Promise.all(names.map((name) => getData(name))); } diff --git a/docs/.vitepress/theme/components/home/HomeIconCustomizer.vue b/docs/.vitepress/theme/components/home/HomeIconCustomizer.vue index 4b69771..53e13f1 100644 --- a/docs/.vitepress/theme/components/home/HomeIconCustomizer.vue +++ b/docs/.vitepress/theme/components/home/HomeIconCustomizer.vue @@ -64,7 +64,7 @@ watch(absoluteStrokeWidth, (enabled) => {

- Lucide has a lot of customization options to match the icons with you UI. + Lucide has a lot of customization options to match the icons with your UI.

diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 15b8ba3..018e5cf 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -28,7 +28,7 @@ For more details, see the [documentation](packages/lucide.md). ## React -Implementation of the lucide icon library for react applications. +Implementation of the lucide icon library for React applications. ::: code-group @@ -47,84 +47,138 @@ npm install lucide-react ::: For more details, see the [documentation](packages/lucide-react.md). +For React Native use the `lucide-react-native` package. -## Vue 2 +## Vue -Implementation of the lucide icon library for vue applications. +Implementation of the lucide icon library for Vue applications. -```bash -yarn add lucide-vue +::: code-group + +```sh [pnpm] +pnpm install lucide-vue-next ``` -or - -```sh -npm install lucide-vue -``` - -For more details, see the [documentation](packages/lucide-vue.md). - -## Vue 3 - -Implementation of the lucide icon library for vue applications. - -```bash +```sh [yarn] yarn add lucide-vue-next ``` -or - -```sh +```sh [npm] npm install lucide-vue-next ``` +::: + For more details, see the [documentation](packages/lucide-vue-next.md). +For Vue 2 use the `lucide-vue` package. ## Svelte -Implementation of the lucide icon library for vue applications. +Implementation of the lucide icon library for Svelte applications. -```bash +::: code-group + +```sh [pnpm] +pnpm install lucide-svelte +``` + +```sh [yarn] yarn add lucide-svelte ``` -or - -```sh +```sh [npm] npm install lucide-svelte ``` +::: + For more details, see the [documentation](packages/lucide-svelte.md). +## Solid + +Implementation of the lucide icon library for Solid applications. + +::: code-group + +```sh [pnpm] +pnpm install lucide-solid +``` + +```sh [yarn] +yarn add lucide-solid +``` + +```sh [npm] +npm install lucide-solid +``` + +::: + +For more details, see the [documentation](packages/lucide-solid.md). + ## Angular -```bash +Implementation of the lucide icon library for Angular applications. + +::: code-group + +```sh [pnpm] +pnpm install lucide-angular +``` + +```sh [yarn] yarn add lucide-angular ``` -or - -```sh +```sh [npm] npm install lucide-angular ``` +::: + For more details, see the [documentation](packages/lucide-angular.md). ## Preact Implementation of the lucide icon library for preact applications. -```bash +::: code-group + +```sh [pnpm] +pnpm install lucide-preact +``` + +```sh [yarn] yarn add lucide-preact ``` -or - -```sh +```sh [npm] npm install lucide-preact ``` -For more details, see the [documentation](packages/lucide-preact.md). +::: + +## Static usage + +Implementation of the lucide icon library for multiple usages that like to use: SVG files icons, SVG Sprite, Icon Fonts and static SVG strings export in Common JS modules (for NodeJS). + +::: code-group + +```sh [pnpm] +pnpm install lucide-static +``` + +```sh [yarn] +yarn add lucide-static +``` + +```sh [npm] +npm install lucide-static +``` + +::: + +For more details, see the [documentation](packages/lucide-static.md). ## Figma @@ -134,16 +188,6 @@ Visit [Figma community page](https://www.figma.com/community/plugin/939567362549 ![Setting Page Size](https://www.figma.com/community/plugin/939567362549682242/thumbnail 'Figma Lucide Cover') -## Laravel - -Implementation of Lucide icon's using `blade-icons` for Laravel based projects. - -```bash -composer require mallardduck/blade-lucide-icons -``` - -For more details, see the [documentation](https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md). - ## Flutter Implementation of Lucide icon library for Flutter applications. diff --git a/docs/guide/packages/lucide-angular.md b/docs/guide/packages/lucide-angular.md index 547aa53..aba4524 100644 --- a/docs/guide/packages/lucide-angular.md +++ b/docs/guide/packages/lucide-angular.md @@ -4,16 +4,22 @@ Implementation of the lucide icon library for Angular applications. ## Installation -```bash +::: code-group + +```sh [pnpm] +pnpm install lucide-angular +``` + +```sh [yarn] yarn add lucide-angular ``` -or - -```bash +```sh [npm] npm install lucide-angular ``` +::: + ## How to use ### Step 1: Import `LucideAngularModule` @@ -98,7 +104,9 @@ To add custom icons, you will first need to convert them to an [svgson format](h ## Loading all icons -> :warning: You may also opt to import all icons if necessary using the following format but be aware that this will significantly increase your application build size. +::: danger +You may also opt to import all icons if necessary using the following format but be aware that this will significantly increase your application build size. +::: ```js import { icons } from 'lucide-angular'; diff --git a/docs/guide/packages/lucide-preact.md b/docs/guide/packages/lucide-preact.md index 640c51f..3f6bcce 100644 --- a/docs/guide/packages/lucide-preact.md +++ b/docs/guide/packages/lucide-preact.md @@ -8,28 +8,34 @@ Implementation of the lucide icon library for preact applications. ## Installation -```sh +::: code-group + +```sh [pnpm] +pnpm install lucide-preact +``` + +```sh [yarn] yarn add lucide-preact ``` -or - -```sh +```sh [npm] npm install lucide-preact ``` +::: + ## How to use -It's build with ESmodules so it's completely tree-shakable. -Each icon can be imported as a preact component. +It's build with ES Modules so it's completely tree-shakable. + +Each icon can be imported as a Preact component, what renders a inline SVG Element. This way only the icons that are imported into your project are included in the final bundle. The rest of the icons are tree-shaken away. ### Example -You can pass additional props to adjust the icon. +Additional props can be passed to adjust the icon: -```js +```jsx import { Camera } from 'lucide-preact'; -// Returns PreactComponent // Usage const App = () => { @@ -39,7 +45,7 @@ const App = () => { export default App; ``` -### Props +## Props | name | type | default | | --------------------- | --------- | ------------ | @@ -48,29 +54,31 @@ export default App; | `strokeWidth` | *number* | 2 | | `absoluteStrokeWidth` | *boolean* | false | -### Custom props / svg attributes +### Applying props -You can also pass custom props that will be added in the as attributes. With that you can modify the icons look by passing svg attributes. +To apply custom props to change the look of the icon, this can be done by simply pass them as props to the component. All SVG attributes are available as props to style the SVGs. See the list of SVG Presentation Attributes on [MDN](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/Presentation). -```js +```jsx // Usage const App = () => { return ; }; ``` -> svg attributes in preact aren't transformed, so if want to change e.g. the `stroke-linejoin` you need to pass it in kebabcase, the way svg spec is written so. See this topic in the [preact documentation](https://preactjs.com/guide/v10/differences-to-react/#svg-inside-jsx). +> SVG attributes in Preact aren't transformed, so if you want to change for example the `stroke-linejoin` you need to pass it in kebabcase. Basically how the SVG spec want you to write it. See this topic in the [Preact documentation](https://preactjs.com/guide/v10/differences-to-react/#svg-inside-jsx). -### One generic icon component +## One generic icon component -It is possible to create one generic icon component to load icons. +It is possible to create one generic icon component to load icons. It's not recommended. -> ⚠️ Example below importing all EsModules, caution using this example, not recommended when you using bundlers, your application build size will grow strongly. +::: danger +Example below importing all ES Modules, caution using this example. All icons will be imported. When using bundlers like: `Webpack`, `Rollup` or `Vite` the application build size will grow strongly and harming the performance the application. +::: -#### Icon Component Example +### Icon Component Example -```js -import * as icons from 'lucide-preact'; +```jsx +import { icons } from 'lucide-preact'; const Icon = ({ name, color, size }) => { const LucideIcon = icons[name]; @@ -80,3 +88,15 @@ const Icon = ({ name, color, size }) => { export default Icon; ``` + +#### Using the Icon Component + +```jsx +import Icon from './Icon'; + +const App = () => { + return ; +}; + +export default App; +``` diff --git a/docs/guide/packages/lucide-react-native.md b/docs/guide/packages/lucide-react-native.md index 51253b2..467b7cb 100644 --- a/docs/guide/packages/lucide-react-native.md +++ b/docs/guide/packages/lucide-react-native.md @@ -6,28 +6,32 @@ Implementation of the lucide icon library for React Native applications First, ensure that you have `react-native-svg@^12.0.0` installed. Then, install the package: -```bash +::: code-group + +```sh [pnpm] +pnpm install lucide-react-native +``` + +```sh [yarn] yarn add lucide-react-native ``` -or - -```sh +```sh [npm] npm install lucide-react-native ``` +::: + ## How to use -It's build with ESmodules so it's completely tree-shakable. -Each icon can be imported as a react component. +Each icon can be imported as a React component. ### Example -You can pass additional props to adjust the icon. +Additional props can be passed to adjust the icon: -```js +```jsx import { Camera } from 'lucide-react-native'; -// Returns ReactComponent // Usage const App = () => { @@ -37,7 +41,7 @@ const App = () => { export default App; ``` -### Props +## Props | name | type | default | | --------------------- | --------- | ------------ | @@ -46,27 +50,29 @@ export default App; | `strokeWidth` | *number* | 2 | | `absoluteStrokeWidth` | *boolean* | false | -### Custom props +### Applying props -You can also pass custom props that will be added in the svg as attributes. +To apply custom props to change the look of the icon, this can be done by simply pass them as props to the component. -```js +```jsx // Usage const App = () => { return ; }; ``` -### One generic icon component +## One generic icon component It is possible to create one generic icon component to load icons. -> :warning: Example below importing all EsModules, caution using this example, not recommended when you using bundlers, your application build size will grow strongly. +::: warning +Example below importing all ES Modules, caution using this example. All icons will be imported. When using bundlers like: `Webpack`, `Rollup` or `Vite` the application build size will grow strongly and harming the performance the application. +::: -#### Icon Component Example +### Icon Component Example -```js -import * as icons from 'lucide-react'; +```jsx +import { icons } from 'lucide-react'; const Icon = ({ name, color, size }) => { const LucideIcon = icons[name]; @@ -76,3 +82,15 @@ const Icon = ({ name, color, size }) => { export default Icon; ``` + +#### Using the Icon Component + +```jsx +import Icon from './Icon'; + +const App = () => { + return ; +}; + +export default App; +``` diff --git a/docs/guide/packages/lucide-react.md b/docs/guide/packages/lucide-react.md index 4c43f1b..6685abd 100644 --- a/docs/guide/packages/lucide-react.md +++ b/docs/guide/packages/lucide-react.md @@ -4,28 +4,34 @@ Implementation of the lucide icon library for react applications ## Installation -```bash +::: code-group + +```sh [pnpm] +pnpm install lucide-react +``` + +```sh [yarn] yarn add lucide-react ``` -or - -```sh +```sh [npm] npm install lucide-react ``` +::: + ## How to use -It's build with ESmodules so it's completely tree-shakable. -Each icon can be imported as a react component. +It's build with ES Modules so it's completely tree-shakable. + +Each icon can be imported as a React component, what renders a inline SVG Element. This way only the icons that are imported into your project are included in the final bundle. The rest of the icons are tree-shaken away. ### Example -You can pass additional props to adjust the icon. +Additional props can be passed to adjust the icon: -```js +```jsx import { Camera } from 'lucide-react'; -// Returns ReactComponent // Usage const App = () => { @@ -35,7 +41,7 @@ const App = () => { export default App; ``` -### Props +## Props | name | type | default | | --------------------- | --------- | ------------ | @@ -44,27 +50,29 @@ export default App; | `strokeWidth` | *number* | 2 | | `absoluteStrokeWidth` | *boolean* | false | -### Custom props +### Applying props -You can also pass custom props that will be added in the svg as attributes. +To apply custom props to change the look of the icon, this can be done by simply pass them as props to the component. All SVG attributes are available as props to style the SVGs. See the list of SVG Presentation Attributes on [MDN](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/Presentation). -```js +```jsx // Usage const App = () => { - return ; + return ; }; ``` -### One generic icon component +## One generic icon component -It is possible to create one generic icon component to load icons. +It is possible to create one generic icon component to load icons. It's not recommended. -> :warning: Example below importing all EsModules, caution using this example, not recommended when you using bundlers, your application build size will grow strongly. +::: danger +Example below importing all ES Modules, caution using this example. All icons will be imported. When using bundlers like: `Webpack`, `Rollup` or `Vite` the application build size will grow strongly and harming the performance the application. +::: -#### Icon Component Example +### Icon Component Example -```js -import * as icons from 'lucide-react'; +```jsx +import { icons } from 'lucide-react'; const Icon = ({ name, color, size }) => { const LucideIcon = icons[name]; @@ -74,3 +82,15 @@ const Icon = ({ name, color, size }) => { export default Icon; ``` + +#### Using the Icon Component + +```jsx +import Icon from './Icon'; + +const App = () => { + return ; +}; + +export default App; +``` diff --git a/docs/guide/packages/lucide-solid.md b/docs/guide/packages/lucide-solid.md index aae3111..97395d0 100644 --- a/docs/guide/packages/lucide-solid.md +++ b/docs/guide/packages/lucide-solid.md @@ -4,28 +4,34 @@ Implementation of the lucide icon library for solid applications. ## Installation -```sh +::: code-group + +```sh [pnpm] +pnpm install lucide-solid +``` + +```sh [yarn] yarn add lucide-solid ``` -or - -```sh +```sh [npm] npm install lucide-solid ``` +::: + ## How to use -It's build with ESmodules so it's completely tree-shakable. -Each icon can be imported as a solid component. +It's build with ES Modules so it's completely tree-shakable. + +Each icon can be imported as a Solid component, what renders a inline SVG Element. This way only the icons that are imported into your project are included in the final bundle. The rest of the icons are tree-shaken away. ### Example -You can pass additional props to adjust the icon. +Additional props can be passed to adjust the icon: -```js +```jsx import { Camera } from 'lucide-solid'; -// Returns SolidComponent // Usage const App = () => { @@ -35,7 +41,7 @@ const App = () => { export default App; ``` -### Props +## Props | name | type | default | | --------------------- | --------- | ------------ | @@ -44,32 +50,37 @@ export default App; | `strokeWidth` | *number* | 2 | | `absoluteStrokeWidth` | *boolean* | false | -### Custom props / svg attributes +### Applying props -You can also pass custom props that will be added in the as attributes. With that you can modify the icons look by passing svg attributes. +To apply custom props to change the look of the icon, this can be done by simply pass them as props to the component. All SVG attributes are available as props to style the SVGs. See the list of SVG Presentation Attributes on [MDN](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/Presentation). -```js +```jsx // Usage const App = () => { return ; }; ``` -### One generic icon component +## One generic icon component -It is possible to create one generic icon component to load icons. +It is possible to create one generic icon component to load icons. It's not recommended. -> :warning: Example below importing all EsModules, caution using this example, not recommended when you using bundlers, your application build size will grow strongly. +::: danger +Example below importing all ES Modules, caution using this example. All icons will be imported. When using bundlers like: `Webpack`, `Rollup` or `Vite` the application build size will grow strongly and harming the performance the application. +::: -#### Icon Component Example +### Icon Component Example ```tsx -import * as icons from 'lucide-solid'; -import type { LucideProps } from 'lucide-solid'; +import { icons, type LucideProps } from 'lucide-solid'; import { splitProps } from 'solid-js'; import { Dynamic } from 'solid-js/web'; -const Icon = (props: { name: keyof typeof icons } & LucideProps) => { +interface IconProps extends LucideProps { + name: keyof typeof icons; +} + +const Icon = (props: IconProps) => { const [local, others] = splitProps(props, ["name"]); return @@ -77,3 +88,15 @@ const Icon = (props: { name: keyof typeof icons } & LucideProps) => { export default Icon; ``` + +#### Using the Icon Component + +```tsx +import Icon from './Icon'; + +const App = () => { + return ; +}; + +export default App; +``` diff --git a/docs/guide/packages/lucide-static.md b/docs/guide/packages/lucide-static.md index 24a1fda..008bb09 100644 --- a/docs/guide/packages/lucide-static.md +++ b/docs/guide/packages/lucide-static.md @@ -11,22 +11,30 @@ This package include the following lucide implementations: This package is suitable for specific use cases, for example if you want to use icon fonts, SVG sprites, normal SVGs or Common.js SVG strings in your javascript project. -> ⚠️ While they can be useful for prototyping, it is not recommended to use the SVG sprites or icon fonts provided by this package in production web apps as all the available icons are included in the app, hence increasing loading time and data usage. We recommend to use a bundler and treeshaking to make sure only the icons you use are bundled with your app. Threeshaking is only available in these packages: [lucide](lucide), [lucide-react](lucide-react), [lucide-vue](lucide-vue), [lucide-vue-next](lucide-vue-next), [lucide-angular](lucide-angular), [lucide-preact](lucide-preact) +::: warning +While they can be useful for prototyping, it is not recommended to use the SVG sprites or icon fonts provided by this package in production web apps as all the available icons are included in the app, hence increasing loading time and data usage. We recommend to use a bundler and tree-shaking to make sure only the icons you use are bundled with your app. Tree-shaking is only available in these packages: [lucide](lucide), [lucide-react](lucide-react), [lucide-vue](lucide-vue), [lucide-vue-next](lucide-vue-next), [lucide-angular](lucide-angular), [lucide-preact](lucide-preact) +::: ## Installation ## Package Managers -```sh +::: code-group + +```sh [pnpm] +pnpm install lucide-static +``` + +```sh [yarn] yarn add lucide-static ``` -or - -```sh +```sh [npm] npm install lucide-static ``` +::: + ### CDN ```html diff --git a/docs/guide/packages/lucide-svelte.md b/docs/guide/packages/lucide-svelte.md index 2c9b0c8..ef4968b 100644 --- a/docs/guide/packages/lucide-svelte.md +++ b/docs/guide/packages/lucide-svelte.md @@ -4,25 +4,33 @@ Implementation of the lucide icon library for svelte applications. ## Installation -```bash +::: code-group + +```sh [pnpm] +pnpm install lucide-svelte +``` + +```sh [yarn] yarn add lucide-svelte ``` -or - -```sh +```sh [npm] npm install lucide-svelte ``` +::: + ## How to use -All the icons are Svelte components, that ouputs Svg elements. So each icon can be imported and used as a component. This also helps with the use of threeshaking so you only import the icons you use. +It's build with ES Modules so it's completely tree-shakable. + +Each icon can be imported as a Svelte component, what renders a inline SVG Element. This way only the icons that are imported into your project are included in the final bundle. The rest of the icons are tree-shaken away. ### Example Default usage: -```html +```svelte @@ -30,9 +38,9 @@ Default usage: ``` -You can pass additional props to adjust the icon. +Additional props can be passed to adjust the icon: -```html +```svelte @@ -40,7 +48,7 @@ You can pass additional props to adjust the icon. ``` -### Available props +## Props | name | type | default | | --------------------- | --------- | ------------ | @@ -48,14 +56,12 @@ You can pass additional props to adjust the icon. | `color` | *string* | currentColor | | `strokeWidth` | *number* | 2 | | `absoluteStrokeWidth` | *boolean* | false | -| `*` | *string* | - | +### Applying props -\* All SVGProps are available to style the svgs. See the list of SVG Presentation Attributes on [MDN](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/Presentation) +To apply custom props to change the look of the icon, this can be done by simply pass them as props to the component. All SVG attributes are available as props to style the SVGs. See the list of SVG Presentation Attributes on [MDN](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/Presentation). -### Example of custom props - -```html +```svelte @@ -65,15 +71,17 @@ You can pass additional props to adjust the icon. This results a filled phone icon. -### One generic icon component +## One generic icon component -It is possible to create one generic icon component to load icons. +It is possible to create one generic icon component to load icons. It's not recommended. -> ⚠️ Example below importing all EsModules, caution using this example, not recommended when you bundle your application,the build size will grow strongly. Because it will import all the icons. +::: danger +Example below importing all ES Modules, caution using this example. All icons will be imported. When using bundlers like: `Webpack`, `Rollup` or `Vite` the application build size will grow strongly and harming the performance the application. +::: -#### Icon Component Example +### Icon Component Example -```html +```svelte ``` + diff --git a/docs/guide/packages/lucide-vue-next.md b/docs/guide/packages/lucide-vue-next.md index f2f74b9..bca36e5 100644 --- a/docs/guide/packages/lucide-vue-next.md +++ b/docs/guide/packages/lucide-vue-next.md @@ -2,32 +2,41 @@ Implementation of the lucide icon library for Vue 3 applications. -> ⚠️ This version of lucide is for Vue 3, For Vue 2 got to [lucide-vue](lucide-vue) +## Vue 3 or Vue 2 + +::: tip +This version of lucide is for Vue 3, For Vue 2 got to [lucide-vue ->](lucide-vue) +::: ## Installation -**With yarn** +::: code-group -```bash +```sh [pnpm] +pnpm install lucide-vue-next +``` + +```sh [yarn] yarn add lucide-vue-next ``` -**With npm** - -```bash +```sh [npm] npm install lucide-vue-next ``` +::: + ## How to use -It's build with ESmodules so it's completely tree-shakable. -Each icon can be imported as a vue component. +It's build with ES Modules so it's completely tree-shakable. + +Each icon can be imported as a Vue component, what renders a inline SVG Element. This way only the icons that are imported into your project are included in the final bundle. The rest of the icons are tree-shaken away. ### Example You can pass additional props to adjust the icon. -``` html +```vue