Skip to content

UI Configuration

UI configuration also known as Client (Frontend) configuration, is the configuration of the Artalk interface.

You can modify the UI configuration in the "Dashboard" without changing the frontend code. Additionally, Configuration files and Environment variables are also supported.

The priority of UI configuration is as follows:

Frontend Code > Environment Variables > Dashboard = Configuration File

If you have modified the UI configuration through environment variables, configuration files, or the Dashboard, but the changes are not taking effect, please consider the issue of UI configuration priority.

Configuring the Interface via Artalk.init

When initializing with Artalk.init on the frontend page, pass parameters to configure the interface. Below are all the available configuration options.

js
const artalk = Artalk.init({
  el:        '#Comments',
  pageKey:   '/post/1', 
  pageTitle: 'Page Title',
  server:    'http://your_domain:8080',
  site:      'Artalk Blog',
})

// Update configuration
artalk.update({ ... })

Basic Configuration (Required)

el

Mount Element (Specify the element selector to bind)

  • Type: String|HTMLElement
  • Default: undefined

Example: #Comments corresponds to the element <div id="Comments"></div>

pageKey

Page Address (Relative path / full URL)

  • Type: String
  • Default: location.pathname

Leave empty to automatically get the relative path of the page.

You can fill in the permalink generated by the blog system, but it is recommended to use the relative path for easier domain switching in the future.

Reference: Using Relative / Absolute Paths

pageTitle

Page Title (Used for management list display, email notifications, etc.)

  • Type: String
  • Default: document.title

Leave empty to automatically get the value of the <title> tag of the page.

server

Backend Program API Address

  • Type: String
  • Default: undefined

Deploy the backend and ensure that the backend address is accessible from the front end.

Example: http://yourdomain.xxx

site

Site Name

  • Type: String
  • Default: undefined

Artalk supports unified management of multiple sites, this item is used for site isolation.

preferRemoteConf

Prefer Remote Configuration

  • Type: Boolean
  • Default: false (disabled by default)

This config option is disabled by default, meaning Artalk will prioritize using local config. Local config refers to the settings passed through Artalk.init in the frontend code.

When enabled, Artalk will prioritize using remote config. If the remote config does not exist, it will resort to using the local config. Remote config refers to the settings returned by the backend server program, allowing for dynamic config of the Artalk client. You can modify the user interface config in the "Dashboard".

Update Notice

As of version v2.10.0, the useBackendConf configuration option has been deprecated and is always true. Please use preferRemoteConf instead.

Internationalization (i18n)

locale

Language

  • Type: String|Object|"auto"
  • Default: "zh-CN"

Following the Unicode BCP 47 standard, the default is "zh-CN" (Simplified Chinese).

Feel free to submit a PR to help translate Artalk into multiple languages and contribute to the community!

For details, see: Localization

dateFormatter

Date Formatting Function

  • Type: (date: Date) => string
  • Default: undefined

By default, it shows a few seconds ago, a few minutes ago, a few hours ago, a few days ago, and if it exceeds 7 days, it shows the specific date in the format YYYY-MM-DD.

You can also customize the date formatting function. Below is an example using toLocaleString and dayjs to format dates.

js
import dayjs from 'dayjs'

Artalk.init({
  dateFormatter: (date) => {
    // return date.toLocaleString()  // '2024/8/28 17:51:31'
    return dayjs(date).fromNow("MMMM D, YYYY h:mm A")  // 'August 28, 2024 5:51 PM'
  },
})

Requests

reqTimeout

Request Timeout

  • Type: Number
  • Default: 15000

Automatically disconnects the request and reports an error if the request time exceeds this value (unit: milliseconds).

Emoticons

emoticons

Emoticons

For details: Frontend · Emoticons

Now compatible with OwO format, supports dynamic loading by URL.

Set to false to disable the emoticon feature.

Interface

placeholder

Comment Box Placeholder Text

  • Type: String
  • Default: "Type something..."

noComment

Text Displayed When There Are No Comments

  • Type: String
  • Default: "「Silence is golden」"

sendBtn

Send Button Text

  • Type: String
  • Default: "Post Comment"

editorTravel

Comment Box Travel

  • Type: Boolean
  • Default: true

Set to true to move the comment box to the position of the comment being replied to, instead of keeping it fixed.

darkMode

Dark Mode

  • Type: Boolean|"auto"
  • Default: false

When Artalk is instantiated, it reads this value and chooses whether to enable dark mode (can be used with the blog theme).

To dynamically modify darkMode:

js
artalk.setDarkMode(true)

Reference code: “index.html

Set to "auto", Artalk will listen to (prefers-color-scheme: dark) and automatically switch to dark mode based on the user's operating system settings.

flatMode

Flat Mode

  • Type: Boolean|"auto"
  • Default: "auto"

By default, "auto" automatically enables "flat mode" on small screen devices (screen width < 768px).

Set to true to display comments in "flat mode".

Set to false to display comments in "nested mode".

nestMax

Maximum Nested Levels

  • Type: Number
  • Default: 2

Maximum nested levels for comments in "nested mode".

nestSort

Sorting Rules for Nested Comments

  • Type: "DATE_ASC"|"DATE_DESC"|"VOTE_UP_DESC"
  • Default: "DATE_ASC"

By default, nested comments are sorted in ascending order by date (new comments at the end).

Features

pvEl

Page Views (PV) Binding Element

  • Type: String
  • Default: ".artalk-pv-count"

You can place an HTML tag anywhere on the page: <span class="artalk-pv-count"></span>

When Artalk finishes loading, it displays the page views.

This item specifies the selector of the binding element, defaulting to .artalk-pv-count.

countEl

Comment Count Binding Element

  • Type: String
  • Default: ".artalk-comment-count"

You can place an HTML tag anywhere on the page: <span class="artalk-comment-count"></span> to display the current page's comment count.

TIP

Both pvEl and countEl element tags can set the data-page-key attribute to specify the statistics of a particular page, for example: <span class="artalk-comment-count" data-page-key="/t/1.html"></span>

For details, see: [PV Statistics](./pv.md#Loading statistics for multiple pages simultaneously)

statPageKeyAttr

Statistical Component PageKey Attribute Name

  • Type: String
  • Default: "data-page-key"

When querying comment counts and page views, Artalk's statistical component uses this attribute name to query the specified page, for example: <span data-page-key="/t/1.html"></span>.

To facilitate theme adaptation, you can customize the attribute name as needed, for example, replacing it with data-path, the HTML tag would be <span data-path="/t/1.html"></span>.

pageVote

Page Voting Buttons

  • Type: Boolean | { upBtnEl: string; downBtnEl: string; upCountEl: string; downCountEl: string; activeClass: string }
  • Default: true

Enable the page voting feature (upvote / downvote).

For details, see: Page Voting

vote

Voting Buttons

  • Type: Boolean
  • Default: true

Enable the comment voting feature (upvote / downvote).

voteDown

Downvote Button

  • Type: Boolean
  • Default: false

Downvote button (hidden by default).

uaBadge

Display User's UserAgent Information Badge

  • Type: Boolean
  • Default: false

listSort

Comment Sorting Feature

  • Type: Boolean
  • Default: true

Hover over the "n comments" in the top left of the comment list to display a floating dropdown, allowing the comment list to be sorted and filtered according to "latest / hottest / earliest / author".

imgUpload

Image Upload Feature

  • Type: Boolean
  • Default: true

This configuration item automatically follows the backend. When the backend image upload feature is disabled, only administrators will see the image upload button.

imgUploader

Image Uploader

  • Type: (file: File) => Promise<string>
  • Default: undefined

Custom image uploader, for example:

js
Artalk.init({
  imgUploader: async (file) => {
    const form = new FormData()
    form.set('file', file)

    const imgUrl = await fetch('https://api.example.org/upload', {
      method: 'POST',
      body: form,
    })

    return imgUrl
  },
})

imgLazyLoad

Lazy Load Images

  • Type: "native"|"data-src"|Boolean
  • Default: false

Enable lazy loading of images in comments.

For details, see: Lazy Load Images

preview

Editor Real-Time Preview Feature

  • Type: Boolean
  • Default: true

Display the "Preview" button in the editor.

Avatars

js
gravatar: {
  mirror: '<Gravatar Mirror URL>',
  default: 'mp',
}

gravatar.mirror

Gravatar Mirror URL

  • Type: String
  • Default: "https://www.gravatar.com/avatar/"

If you find Gravatar avatar loading speed unsatisfactory, you can try replacing it.

For example:

WeAvatar: https://weavatar.com/avatar/

Cravatar: https://cravatar.cn/avatar/

V2EX: https://cdn.v2ex.com/gravatar/

Geekzu: https://sdn.geekzu.org/avatar/

Loli: https://gravatar.loli.net/avatar/

gravatar.params

Gravatar API Parameters

  • Type: String
  • Default: "sha256=1&d=mp&s=240"

For example, you can set the default avatar (d=mp) and avatar size (s=240) through this configuration item.

Reference: Gravatar API Documentation

This configuration item is in HTTP Query format.

Update Notice

v2.8.7 supports generating Gravatar avatar links using the SHA256 encryption algorithm to enhance user privacy protection. Please include sha256=1 in params to enable this encryption (#874).

v2.5.5 deprecated the gravatar.default configuration item; please use gravatar.params instead.

avatarURLBuilder

Avatar URL Builder

  • Type: (comment: CommentData) => string
  • Default: undefined

Custom user avatar image URL generator, for example:

js
Artalk.init({
  avatarURLBuilder: (comment) => {
    return `/api/avatar?email=${comment.email_encrypted}`
  },
})

Comment Pagination

js
pagination: {
  pageSize: 20,   // Number of comments per page
  readMore: true, // Load more or pagination
  autoLoad: true, // Auto-load (load more)
}

pagination.readMore

Load More Mode

  • Type: Boolean
  • Default: true

Set to true for "Load More" mode.

Set to false for "Pagination" mode.

pagination.autoLoad

Auto-Load on Scroll

  • Type: Boolean
  • Default: true

(Must enable "Load More" mode by setting readMore to true)

pagination.pageSize

Number of Comments Per Request

  • Type: Number
  • Default: 20

Content Height Limit

Content exceeding the set height will be hidden, and a "Read More" button will be displayed.

js
heightLimit: {
  content: 300, // Comment content height limit
  children: 400, // Child comment area height limit
  scrollable: false, // Height limit scrolling
}

heightLimit.content

Comment Content Height Limit

  • Type: Number
  • Default: 300

Set to 0 to disable height limit.

heightLimit.children

Child Comment Area Height Limit

  • Type: Number
  • Default: 400

heightLimit.scrollable

Scrollable Height Limit Area

  • Type: Boolean
  • Default: false

Allow height limit area to scroll.

Version Check

versionCheck

Version Check

  • Type: Boolean
  • Default: true

Display a warning prompt when the frontend and backend versions are incompatible.

Contributors

Changelog