https://docs.flarum.org/assets/js/bfbff823.8db9262a.js

1"use strict";(globalThis.webpackChunkflarum_docs=globalThis.webpackChunkflarum_docs||[]).push([[4736],{9183(e,s,n){n.r(s),n.d(s,{assets:()=>c,contentTitle:()=>t,default:()=>h,frontMatter:()=>o,metadata:()=>r,toc:()=>l});const r=JSON.parse('{"id":"fontawesome","title":"FontAwesome Icons","description":"Flarum uses FontAwesome for icons throughout the interface. By default the Free tier is bundled with Flarum and served from your own server. You can switch to a CDN-hosted stylesheet or a FontAwesome Kit to unlock Pro icons, custom icons, and other features.","source":"@site/docs/fontawesome.md","sourceDirName":".","slug":"/fontawesome","permalink":"/fontawesome","draft":false,"unlisted":false,"editUrl":"https://github.com/flarum/docs/tree/main/docs/fontawesome.md","tags":[],"version":"current","frontMatter":{},"sidebar":"guideSidebar","previous":{"title":"Theming","permalink":"/themes"},"next":{"title":"Email Configuration","permalink":"/mail"}}');var d=n(4848),i=n(8453);const o={},t="FontAwesome Icons",c={},l=[{value:"Sources",id:"sources",level:2},{value:"Local (default)",id:"local-default",level:3},{value:"CDN",id:"cdn",level:3},{value:"Kit",id:"kit",level:3},{value:"Icon Class Names",id:"icon-class-names",level:2},{value:"Renamed Icons in FA7",id:"renamed-icons-in-fa7",level:2},{value:"Extension Development",id:"extension-development",level:2}];function a(e){const s={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,d.jsxs)(d.Fragment,{children:[(0,d.jsx)(s.header,{children:(0,d.jsx)(s.h1,{id:"fontawesome-icons",children:"FontAwesome Icons"})}),"\n",(0,d.jsxs)(s.p,{children:["Flarum uses ",(0,d.jsx)(s.a,{href:"https://fontawesome.com",children:"FontAwesome"})," for icons throughout the interface. By default the ",(0,d.jsx)(s.strong,{children:"Free"})," tier is bundled with Flarum and served from your own server. You can switch to a CDN-hosted stylesheet or a FontAwesome Kit to unlock Pro icons, custom icons, and other features."]}),"\n",(0,d.jsxs)(s.p,{children:["The active source can be changed from the admin dashboard (",(0,d.jsx)(s.strong,{children:"Admin \u2192 Advanced"}),") or directly in ",(0,d.jsx)(s.a,{href:"/config",children:(0,d.jsx)(s.code,{children:"config.php"})}),"."]}),"\n",(0,d.jsx)(s.h2,{id:"sources",children:"Sources"}),"\n",(0,d.jsx)(s.h3,{id:"local-default",children:"Local (default)"}),"\n",(0,d.jsxs)(s.p,{children:["Flarum ships FontAwesome Free and publishes the webfonts to ",(0,d.jsx)(s.code,{children:"public/assets/fonts/"})," during installation and whenever you run:"]}),"\n",(0,d.jsx)(s.pre,{children:(0,d.jsx)(s.code,{className:"language-bash",children:"php flarum assets:publish\n"})}),"\n",(0,d.jsxs)(s.p,{children:["No external requests are made. Only the ",(0,d.jsx)(s.strong,{children:"Free"})," icon set is available (",(0,d.jsx)(s.code,{children:"fas"}),", ",(0,d.jsx)(s.code,{children:"far"}),", ",(0,d.jsx)(s.code,{children:"fab"}),")."]}),"\n",(0,d.jsx)(s.p,{children:"This is the recommended default for most installations."}),"\n",(0,d.jsxs)(s.admonition,{title:"After upgrading Flarum",type:"tip",children:[(0,d.jsxs)(s.p,{children:["If you upgrade Flarum and the new release ships a different FontAwesome version, old font files in ",(0,d.jsx)(s.code,{children:"public/assets/fonts/"})," are not automatically removed. Clear the directory and re-publish:"]}),(0,d.jsx)(s.pre,{children:(0,d.jsx)(s.code,{className:"language-bash",children:"rm -rf public/assets/fonts\nphp flarum assets:publish\n"})})]}),"\n",(0,d.jsx)(s.h3,{id:"cdn",children:"CDN"}),"\n",(0,d.jsx)(s.p,{children:"Load FontAwesome from a third-party CDN by providing a CSS URL. This replaces the local stylesheet and webfonts entirely \u2014 no fonts are published to your server."}),"\n",(0,d.jsxs)(s.p,{children:["In ",(0,d.jsx)(s.code,{children:"config.php"}),":"]}),"\n",(0,d.jsx)(s.pre,{children:(0,d.jsx)(s.code,{className:"language-php",children:"'fontawesome' => [\n    'source' => 'cdn',\n    'cdn_url' => 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.0/css/all.min.css',\n],\n"})}),"\n",(0,d.jsxs)(s.p,{children:["You can point ",(0,d.jsx)(s.code,{children:"cdn_url"})," at any compatible FontAwesome stylesheet, including Pro CSS files hosted on a private CDN."]}),"\n",(0,d.jsx)(s.h3,{id:"kit",children:"Kit"}),"\n",(0,d.jsxs)(s.p,{children:["A ",(0,d.jsx)(s.a,{href:"https://fontawesome.com/kits",children:"FontAwesome Kit"})," is a personalised bundle configured on the FontAwesome website. Kits are loaded via a JavaScript snippet and unlock features not available with the Free tier:"]}),"\n",(0,d.jsxs)(s.ul,{children:["\n",(0,d.jsxs)(s.li,{children:[(0,d.jsx)(s.strong,{children:"Pro icons"})," \u2014 thousands of additional icons across Solid, Regular, Light, Thin, and Duotone styles"]}),"\n",(0,d.jsxs)(s.li,{children:[(0,d.jsx)(s.strong,{children:"Custom icons"})," \u2014 upload your own SVGs and use them like any FA icon"]}),"\n",(0,d.jsxs)(s.li,{children:[(0,d.jsx)(s.strong,{children:"Icon uploads"})," \u2014 manage icons directly from the FontAwesome dashboard"]}),"\n"]}),"\n",(0,d.jsxs)(s.p,{children:["To use a Kit, create one at ",(0,d.jsx)(s.a,{href:"https://fontawesome.com/kits",children:"fontawesome.com/kits"}),", then add the kit URL to ",(0,d.jsx)(s.code,{children:"config.php"}),":"]}),"\n",(0,d.jsx)(s.pre,{children:(0,d.jsx)(s.code,{className:"language-php",children:"'fontawesome' => [\n    'source' => 'kit',\n    'kit_url' => 'https://kit.fontawesome.com/YOUR_KIT_CODE.js',\n],\n"})}),"\n",(0,d.jsx)(s.p,{children:"The kit URL can be found on your kit's page in the FontAwesome dashboard."}),"\n",(0,d.jsx)(s.admonition,{type:"caution",children:(0,d.jsxs)(s.p,{children:["Kit scripts are loaded from FontAwesome's servers. This means user browsers will make a request to ",(0,d.jsx)(s.code,{children:"kit.fontawesome.com"})," on every page load. If you have strict data-residency requirements, use the CDN or Local source instead."]})}),"\n",(0,d.jsx)(s.h2,{id:"icon-class-names",children:"Icon Class Names"}),"\n",(0,d.jsxs)(s.p,{children:["Flarum uses FontAwesome 7. Icon classes follow the ",(0,d.jsx)(s.code,{children:"{style} {icon}"})," pattern:"]}),"\n",(0,d.jsxs)(s.table,{children:[(0,d.jsx)(s.thead,{children:(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.th,{children:"Style"}),(0,d.jsx)(s.th,{children:"FA7 class"}),(0,d.jsx)(s.th,{children:"Legacy alias (also valid)"})]})}),(0,d.jsxs)(s.tbody,{children:[(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:"Solid"}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-solid fa-house"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fas fa-house"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:"Regular"}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-regular fa-envelope"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"far fa-envelope"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:"Brands"}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-brands fa-github"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fab fa-github"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsxs)(s.td,{children:["Light ",(0,d.jsx)(s.em,{children:"(Pro)"})]}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-light fa-house"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fal fa-house"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsxs)(s.td,{children:["Thin ",(0,d.jsx)(s.em,{children:"(Pro)"})]}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-thin fa-house"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fat fa-house"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsxs)(s.td,{children:["Duotone ",(0,d.jsx)(s.em,{children:"(Pro)"})]}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-duotone fa-house"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fad fa-house"})})]})]})]}),"\n",(0,d.jsxs)(s.p,{children:["The legacy shorthand aliases (",(0,d.jsx)(s.code,{children:"fas"}),", ",(0,d.jsx)(s.code,{children:"far"}),", ",(0,d.jsx)(s.code,{children:"fab"}),", etc.) are fully supported and do not need to be changed. New code may use either style."]}),"\n",(0,d.jsxs)(s.p,{children:["Browse the free icon catalogue at ",(0,d.jsx)(s.a,{href:"https://fontawesome.com/icons",children:"fontawesome.com/icons"}),"."]}),"\n",(0,d.jsx)(s.h2,{id:"renamed-icons-in-fa7",children:"Renamed Icons in FA7"}),"\n",(0,d.jsxs)(s.p,{children:["FontAwesome 7 renamed a number of icons. The old names continue to work via CSS aliases that FA7 ships, so ",(0,d.jsx)(s.strong,{children:"nothing breaks"}),". However, if you are writing new code or updating an existing extension you should prefer the current canonical names."]}),"\n",(0,d.jsx)(s.p,{children:"The following FA5/FA6 icon names used in Flarum core and bundled extensions have been renamed in FA7:"}),"\n",(0,d.jsxs)(s.table,{children:[(0,d.jsx)(s.thead,{children:(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.th,{children:"Old name (FA5/FA6)"}),(0,d.jsx)(s.th,{children:"FA7 canonical name"})]})}),(0,d.jsxs)(s.tbody,{children:[(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-cog"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-gear"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-edit"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-pen-to-square"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-ellipsis-h"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-ellipsis"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-exclamation-triangle"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-triangle-exclamation"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-file-alt"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-file-lines"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-search"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-magnifying-glass"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsxs)(s.td,{children:[(0,d.jsx)(s.code,{children:"fa-sync"})," / ",(0,d.jsx)(s.code,{children:"fa-sync-alt"})]}),(0,d.jsxs)(s.td,{children:[(0,d.jsx)(s.code,{children:"fa-arrows-rotate"})," / ",(0,d.jsx)(s.code,{children:"fa-rotate"})]})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-times"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-xmark"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-times-circle"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-circle-xmark"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-trash-alt"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-trash-can"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-user-edit"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-user-pen"})})]}),(0,d.jsxs)(s.tr,{children:[(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-vote-yea"})}),(0,d.jsx)(s.td,{children:(0,d.jsx)(s.code,{children:"fa-check-to-slot"})})]})]})]}),"\n",(0,d.jsxs)(s.p,{children:["The style prefix (",(0,d.jsx)(s.code,{children:"fas"}),", ",(0,d.jsx)(s.code,{children:"far"}),", etc.) is unchanged for all of the above."]}),"\n",(0,d.jsxs)(s.p,{children:["For the full list of changes, see the ",(0,d.jsx)(s.a,{href:"https://docs.fontawesome.com/web/setup/upgrade/",children:"FontAwesome upgrade guide"}),"."]}),"\n",(0,d.jsx)(s.h2,{id:"extension-development",children:"Extension Development"}),"\n",(0,d.jsxs)(s.p,{children:["When registering an icon from an extension (e.g. in ",(0,d.jsx)(s.code,{children:"composer.json"})," or a settings registration), use the full class string:"]}),"\n",(0,d.jsx)(s.pre,{children:(0,d.jsx)(s.code,{className:"language-json",children:'"icon": "fas fa-puzzle-piece"\n'})}),"\n",(0,d.jsx)(s.p,{children:"Extensions do not need to bundle FontAwesome themselves \u2014 it is provided by Flarum core and available on every page."})]})}function h(e={}){const{wrapper:s}={...(0,i.R)(),...e.components};return s?(0,d.jsx)(s,{...e,children:(0,d.jsx)(a,{...e})}):a(e)}},8453(e,s,n){n.d(s,{R:()=>o,x:()=>t});var r=n(6540);const d={},i=r.createContext(d);function o(e){const s=r.useContext(i);return r.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function t(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(d):e.components||d:o(e.components),r.createElement(i.Provider,{value:s},e.children)}}}]);