SvelteCMS Object Reference
Admin Page
An Admin Page provides a configuration or information page for the Admin UI. Admin Pages are provided by plugins.
Admin Pages do not have shared configurable properties.
Component
Components are .svelte files used to display content. Some are provided by plugins, but they can also be created by developers for a particular app or website.
Components do not have shared configurable properties, though individual Components may have configurable options.
Content Store
A Content Store connects with some type of database or file system to provide storage for content managed by SvelteCMS.
Content Stores do not have shared configurable properties, though individual Content Stores may have configurable options.
Content Stores
staticFiles
option
type
default
script
description
databaseName
text
""
The name used for saving files in-browser. This is required if you are using the browser-based filesystem. It should be globally unique and generally should be the same across one site or app; your site url might be a good choice. At the moment, if you are using something like isomorphic-git, you must import content into the browser filesystem yourself.
contentDirectory
text
"src/content"
The directory for local content files relative to the project root. At the moment, this is hard-coded to "src/content", and changing it can break listing and getting content for that Content Type during `vite build` processes.
fileExtension
text
"md"
What type of file to use for new content; must be one of "md", "json", "yml", or "yaml"
markdownBodyField
text
"body"
Which field should be used as the body of the Markdown file
Content Type
Content Types are the basic data structures of SvelteCMS. Each Content Type specifies how to enter, save, retrieve, display, and delete a document of its type.
property
type
default
script
description
label
text
""
The label for the content type.
contentStore
entity
undefined
The content store which will hold the content.
mediaStore
entity
undefined
The content store which will hold the content.
slug
entity
""
The fields used for the slug of the content type.
Content Types
-
page
title, slug, header, body, footer
-
blog
image, title, date, body, tags
Display
A Display configuration is part of the configuraiton for a Field, Fieldgroup, or ContentType which determines how it will be displayed by SvelteCMS.
property
type
default
script
description
type
text
""
An HTML element (p, li, etc.) or ID of a registered SvelteCMS Component to use when displaying the field.
wrapper
text
""
An HTML element (div, ul, etc.) or ID of a registered SvelteCMS Component to use as a wrapper for the displayed field.
label
text
""
An HTML element (div, span.label, etc.) or ID of a registered SvelteCMS Component to use when displaying the Field label.
html
boolean
false
Whether to treat the field value as pre-sanitized HTML. NOTE! Unless the user input for the field is sanitized with an appropriate and properly configured preMount Transformer, using this feature is a critical security vulnerability.
link
boolean
false
Whether to display the field value as a link to its parent Content.
multiple
boolean
false
Whether to handle multiple values with this display.
Field
Fields are the basic data structures of SvelteCMS, used to compose Content Types and Fieldgroups. Each field stores a particular type of data, which is input using an applicable Widget.
property
type
default
script
description
label
text
""
yes
The label for the field.
widget
entity
""
The form widget used for data input for this field.
index
boolean
false
yes
Whether the field data should be indexed.
mediaStore
entity
""
Where any media uploaded to this field will be stored. Only applies if the widget handles media.
mediaTypes
text
["image/*"]
A list of unique file type specifiers, e.g. "image/jpeg" or ".jpg".
helptext
text
""
yes
The help text to describe the purpose of the field for content editors.
class
text
""
yes
Any classes to add to the form and display.
required
boolean
false
yes
Whether the field is required.
hidden
boolean
false
yes
Whether the field is hidden.
disabled
boolean
false
yes
Whether the field is disabled.
multiple
boolean
false
yes
Whether the field takes multiple values.
multipleOrSingle
boolean
false
Whether the field will allow storing a single value instead of a single-item array.
multipleLabelFields
text
""
yes
For fieldgroups, the fields to concatenate when creating a label for each item.
preSave
entity
[]
Any transformers to apply before the field is saved to storage.
preMount
entity
[]
Any transformers to apply before the field is displayed on the page.
default
defaultValue
undefined
yes
The default value for this field when new content is created.
Field Types
-
text
text, number, range, date, textarea, select, options, value, reference, multiselect
-
date
text, date, select, options, value
-
-
-
-
fieldgroup
fieldgroup, value
-
number
text, number, range, select, options, value, multiselect
-
float
select, options, value, multiselect
-
boolean
checkbox, value, checkbox-text
-
-
-
Fieldgroup
A Fieldgroup is a group of Fields which may be displayed by a Component.
property
type
default
script
description
tags
text
[]
Fields with "Use Components" checked can specify which Fieldgroups may be chosen by ID or by Tags.
Fieldgroups
markdown
option
type
default
script
description
tags
text
[]
Fields with "Use Components" checked can specify which Fieldgroups may be chosen by ID or by Tags.
fields
entityList
undefined
The Fields for this Fieldgroup
image
option
type
default
script
description
tags
text
[]
Fields with "Use Components" checked can specify which Fieldgroups may be chosen by ID or by Tags.
fields
entityList
undefined
The Fields for this Fieldgroup
Hook
A Hook is a function provided by a Plugin that executes at a certain point in the content life cycle.
Hooks do not have shared configurable properties.
Indexer
An Indexer maintains an index of content and media.
property
type
default
script
description
mediaKeys
text
"type,size,height,width,duration,date"
The media fields to index for media from a particular Media Store.
Indexers
staticFiles
option
type
default
script
description
mediaKeys
text
"type,size,height,width,duration,date"
The media fields to index for media from a particular Media Store.
databaseName
text
""
The name used for saving files in-browser. This is required if you are using the browser-based filesystem. It should be globally unique and generally should be the same across one site or app; your site url might be a good choice. At the moment, if you are using something like isomorphic-git, you must import content into the browser filesystem yourself.
Media Store
A Media Store provides storage for images, audio or video, documents, or other files.
Media Stores do not have shared configurable properties, though individual Media Stores may have configurable options.
Media Stores
staticFiles
option
type
default
script
description
databaseName
text
""
The name used for saving files in-browser. This is required if you are using the browser-based filesystem. It should be globally unique and generally should be the same across one site or app; your site url might be a good choice. At the moment, if you are using something like isomorphic-git, you must import content into the browser filesystem yourself.
staticDirectory
text
"static"
The directory for static files relative to the project root. For SvelteKit projects this is "static" by default.
mediaDirectory
text
""
The directory for media files relative to the static directory.
maxUploadSize
text
""
The maximum file size allowed for media uploads, e.g. "10MB". Empty or 0 for unlimited.
Plugin
Plugins add functionality and/or configuration to the SvelteCMS instance.
Plugins do not have shared configurable properties, though individual Plugins may have configurable options.
Plugins
staticFiles
markdown
defaultContent
math
checkboxes
Script Function
Script Functions provide dynamic values for some properties and options of Fields and Widgets when editing and saving content, allowing for conditional and calculated fields, for example.
Script Functions do not have shared configurable properties, though individual Script Functions may have configurable options.
Script Functions
now
Returns the current date.
contains
Determines whether string or array contains a particular value.
option
type
default
script
description
textOrArray
text
""
A string or array which may or may not contain the value.
searchFor
text
""
The value for which to test.
once
Runs a function once only, when the form is first loaded.
option
type
default
script
description
function
text
null
A function to run once.
transform
Runs a Transformer function on a value. Note that the Transformer options cannot be set on this Function; if the defaults must be overridden, then a new Transformer should be created of the type desired.
option
type
default
script
description
value
text
{"function":"getValue"}
The value to be transformed.
transformer
text
null
The ID of the transformer to run.
getProperty
Gets a single property from the Entity being configured. Shortname: "$prop" or "$props.[PropertyName]".
option
type
default
script
description
property
text
""
The name of the property to get.
setProperty
Sets a single property on the Entity being configured.
option
type
default
script
description
property
text
""
The name of the field property to set.
value
text
""
The value to set.
id
Gets the ID of the Entity being configured. Shortname: "$id".
getValue
Gets the value of a field from the form being submitted. Shortname: "$value" or "$values.[FieldID]"
option
type
default
script
description
fieldID
text
{"function":"id"}
The name of the item field to get. Defaults to the current field, so "$value" === "$values($id)".
noFallback
boolean
false
If this is a nested form item and the value is not found at the full path, PREVENT falling back to the root values.
setValue
Sets the value of a field.
option
type
default
script
description
fieldID
text
{"function":"id"}
The name of the item field which should be set to a value.
value
text
""
The value to set.
noFallback
boolean
false
If this is a nested form item and the value is not found at the full path, PREVENT falling back to the root values.
isError
Determines whether a field has an error. Shortname: "$errors" or "$errors.[FieldID]". UNUSED AS YET: requires validators.
option
type
default
script
description
fieldID
text
{"function":"id"}
The name of the item field to check for errors.
noFallback
boolean
false
If this is a nested form item and the value is not found at the full path, PREVENT falling back to the root values.
isTouched
Determines whether a field has been touched. Shortname: "$touched" or "$touched.[FieldID]".
option
type
default
script
description
fieldID
text
{"function":"id"}
The name of the item field to check if it was touched.
noFallback
boolean
false
If this is a nested form item and the value is not found at the full path, PREVENT falling back to the root values.
not
Negates the value of the provided parameter.
option
type
default
script
description
value
text
{"function":"getValue"}
The value to be tested for "truthiness"--returns true for: false, 0, null, undefined, and empty strings.
if
A conditional or ternary operator, with the condition to be tested first, followed by the value if true and then the value if false.
option
type
default
script
description
condition
text
"The condition to be tested."
ifTrue
text
true
The function to run or value to return if true.
ifFalse
text
false
The function to run or value to return if false.
or
Tests if any of the parameters are truthy.
option
type
default
script
description
conditions
text
[]
The conditions or values to be tested for truthiness.
and
Tests if all of the parameters are truthy.
option
type
default
script
description
conditions
text
[]
The conditions or values to be tested for truthiness.
equal
Tests if all of the parameters are equal. Should work with arrays.
option
type
default
script
description
values
text
[]
The values to be tested for equality, using isEqual from lodash.
isLessThan
Tests whether one value is less than another. Also supports less than or equal.
option
type
default
script
description
value
text
""
The base value.
isLessThan
text
""
The test value. Returns true if test value is less than the base value.
orEqual
boolean
false
If true, returns true if the test value is equal to the base value.
isGreaterThan
Tests whether one value is greater than another. Also supports greater than or equal.
option
type
default
script
description
value
text
""
The base value.
isGreaterThan
text
""
The test value. Returns true if test value is greater than the base value.
orEqual
boolean
false
If true, returns true if the test value is equal to the base value.
isNull
Tests whether a value is the "null" value.
option
type
default
script
description
value
text
{"function":"getValue"}
The test value. Returns true if test value is null or undefined.
concat
Concatenates several strings into a single string. Shorthand for join("",[...values]).
option
type
default
script
description
strings
text
""
List of strings to concatenate.
join
Joins several values into a string using a particular join string.
option
type
default
script
description
joinString
text
" "
The string of characters used to join the provided values.
values
text
""
List of strings to join with the join string.
length
Gets the length of a string or array.
option
type
default
script
description
value
text
""
A string or array for which to get the number of characters or items.
typeof
Gets the variable type of a value, or tests that a value matches a particular type.
option
type
default
script
description
value
text
""
A value of which to get the type. Generally only useful with a script function.
type
text
""
The type that the value should be in order to pass this test.
debug
Logs the value of the parameter to the console.
option
type
default
script
description
value
text
""
The value to return after debugging.
mathAdd
Adds two or more numbers together.
option
type
default
script
description
numbers
number
undefined
A list of two or more numbers.
mathSubtract
Subtracts the second number from the first number, then the third from the result, etc.
option
type
default
script
description
numbers
number
undefined
A list of two or more numbers.
mathMultiply
Multiplies two or more numbers together.
option
type
default
script
description
numbers
number
undefined
A list of two or more numbers.
mathDivide
Divides the first number by the second, then the result by the third, etc.
option
type
default
script
description
numbers
number
undefined
A list of two or more numbers.
Slug
A Slug configuration specifies how SvelteCMS will create a "slug" for each piece of content. Slugs are strings of characters, usually only lowercase letters and numbers, dashes, and underscores. SvelteCMS uses slugs to index and reference content. Each piece of content in any content type must have a unique slug. By default, the slug will form a part of the URL at which the content is available.
property
type
default
script
description
fields
text
""
A comma-separated list of field IDs. The value of those fields are combined to form the slug, which is used as the key in key-value databases and as part of the URL for viewing the content on a website.
separator
text
"-"
The separator character will be placed between words in the slug.
slugify
entity
""
Any transformers to apply in creating the slug. Transformers are applied to each field value individually, then the results combined.
Transformer
Transformers modify a Field's data before saving to the database (preSave) or displaying in the browser (preMount).
Transformers do not have shared configurable properties, though individual Transformers may have configurable options.
Transformers
toString
Converts a Field value to a string.
date
Converts a Field value to a Date.
removeTimestamp
Removes the timestamp from a Date field value.
boolean
Converts a Field value to Boolean.
parseInt
Converts a Field value to a number using parseInt.
parseFloat
Converts a Field value to a number using parseFloat.
delete
Removes a Field value from the Fieldgroup or Content Type.
tags
Converts a text Field value to an array of strings, like tags.
option
type
default
script
description
delimiter
text
","
The delimiter between tags.
splitOnSpaces
boolean
false
If true, any space will also function as a delimiter between tags.
trimItems
boolean
true
Whether to trim spaces around tags. Only set to false if it is necessary to begin or end tags with a space character. Does nothing if "Split On Spaces" is false.
slugify
Converts a Field value to a slugified string.
option
type
default
script
description
separator
text
"-"
The separator character to subsitute for spaces, etc.
lowercase
boolean
true
Make the slug lowercase.
decamelize
boolean
true
Convert camelcase to separate words, e.g. fooBar > foo-bar.
customReplacements
text
[]
Add your own custom replacements. The replacements are run on the original string before any other transformations. The format is "from:to,from2:to2,...". To remove a character, use "from:". Add a leading and trailing space to the replacement to have it separated by dashes, e.g. "@: at ,...".
preserveLeadingUnderscore
boolean
false
If your string starts with an underscore, it will be preserved in the slug.
preserveTrailingDash
boolean
false
If your string ends with a dash, it will be preserved in the slug.
getFilename
Gets a filename from a Field value; useful for Fields that handle media.
markdown
Converts Markdown text to HTML using a Markdown processor (by default markdown-it).
Widget
Widgets provide form inputs for entering data into fields.
Widgets do not have shared configurable properties, though individual Widgets may have configurable options.
Widget Types
text
A plain text input.
option
type
default
script
description
placeholder
text
""
yes
This text will be displayed when the field is empty.
fieldgroup
The Widget for fieldgroups with nested fields.
option
type
default
script
description
useComponents
boolean
false
Allow users to choose a Fieldgroup Component when editing.For component-driven content, choose this option and set field.multiple.
fieldgroupTags
text
[]
Allow the specified fieldgroup formats to be chosen by the editors. To allow only specific fieldgroups, set this field blank.
fieldgroups
text
[]
Allow the specified fieldgroups to be chosen by the editors.
oneline
boolean
false
Attempts to make the fieldgroup display in a single line using CSS. This may make a simple fieldgroup widget look like a spreadsheet entry form, but it is not very robust.
number
An HTML number input.
option
type
default
script
description
min
number
0
yes
The minimum number allowed on the form. Does not validate form submissions!
max
number
undefined
yes
The maximum number allowed on the form. Does not validate form submissions!
step
number
1
yes
The amount between each selectable value, e.g. "2" would allow 0,2,4,6.... Does not validate form submissions!
range
An HTML range input with a slider.
option
type
default
script
description
min
number
0
yes
The minimum number allowed on the form. Does not validate form submissions!
max
number
5
yes
The maximum number allowed on the form. Does not validate form submissions!
step
number
1
yes
The amount between each selectable value, e.g. "2" would allow 0,2,4,6.... Does not validate form submissions!
showValue
boolean
true
yes
Whether to show the exact value while editing.
showScale
boolean
true
yes
Whether to show min and max values when editing.
items
list
[]
yes
Text values that correspond to a certain value or range of values, similar to value:label items for a select input. The list must be keyed with numbers, e.g. "0:low", "3:medium", "8:high".
date
An HTML date input, with options for whether and how to store the time.
option
type
default
script
description
time
text
""
yes
Whether and how to store the time. Choosing "none" will store only the date
as yyyy-mm-dd; which is useful when using the date widget with a text field, or as a slug,
but not useful for saving dates. "Time only" is similar, but stores only a time in hours
and minutes. Either of the other two will store a full UTC date, including time.
Sometimes it may be best to hide the time input, e.g. if you are interested only in
when a piece of content is posted and would like to simplify the form.
minDate
date
""
yes
The earliest date allowable.
maxDate
date
""
yes
The latest date allowable.
seconds
boolean
false
yes
Whether to store and keep seconds in the time.
minTime
date
""
yes
The earliest time allowed.
maxTime
date
""
yes
The latest time allowed.
textarea
An HTML textarea input.
option
type
default
script
description
placeholder
text
""
yes
This text will be displayed when the field is empty.
rows
number
3
yes
The height, in "rows", of the textarea element.
cols
number
20
yes
The width, in "columns", of the textarea element.
resize
text
"none"
yes
Whether to allow resizing of the textarea element.
autosize
boolean
false
yes
If selected, the textarea element will be automatically resized to accommodate the entered text.
checkbox
An HTML checkbox form element.
option
type
default
script
description
labelBeforeCheckbox
boolean
false
yes
Render the text label before the checkbox element in HTML markup.
image
The default SvelteCMS image input. Handles multiple images with alt and title fields, but no drag and drop.
option
type
default
script
description
accept
text
"image/*"
A list of unique file type specifiers, e.g. "image/jpeg" or ".jpg".
altField
boolean
true
Show a field for the "alt" attribute
altRequired
boolean
false
Require "alt" attribute
titleField
boolean
false
Show a field for the "title" attribute
attributionField
boolean
false
Show a field for license or attribution of the image
attributionRequired
boolean
false
Require the attribution field
file
The default cms file input. Handles multiple files.
option
type
default
script
description
accept
text
undefined
A list of unique file type specifiers, e.g. "image/jpeg" or ".jpg".
storeStats
boolean
undefined
Store type, size, and upload date for each file in the database.
titleField
boolean
false
Show a field for the "title" attribute
attributionField
boolean
false
Show a field for license or attribution of the image
attributionRequired
boolean
false
Require the attribution field
hideHeader
boolean
false
Hide the header for the table of files
select
An HTML select box.
option
type
default
script
description
size
number
0
yes
The maximum number of items shown in the dropdown area of a select box.
unset
text
""
yes
The title text to use for a blank entry. If this is provided, or if the field is not required, a blank value will be available. The default title for the blank value is "- none -".
items
list
[]
yes
The list of values allowed for this select input, along with the labels for display.
options
Options presented as option buttons or checkboxes.
option
type
default
script
description
items
list
[]
yes
The list of values allowed for this options field, along with the labels for display.
value
This widget allows providing a calculated value using a Script Function. The value may be hidden or displayed during editing. THIS WIDGET DOES NOT PROVIDE SECURITY! Even if not displayed, this field and its value are still available in clients / browsers, and the value can still be modified before the form is submitted. NEVER expect this widget to keep sensitive data safe, and NEVER trust the data received from it without validating it.
option
type
default
script
description
value
text
""
yes
The value of the field. Use a Script Function to determine this based on other fields.
display
boolean
false
yes
Can display the calculated value on the editing form in a disabled text field.
reference
A reference to another Content item.
option
type
default
script
description
contentTypes
text
undefined
An ID for the field's index, or one or more Content Type IDs. For free tagging, this MUST be a single value, which MAY have an associated Content Type.
freeTagging
boolean
false
If false, only existing content items will be allowed.
displayKey
text
"title"
The field used for search and display on form inputs, and for storing the display value for free tagging. If this field is linked with Content Types, then each linked Content Type should have an indexed field with this ID. For free tagging, or when not linked to a Content Type, you can use any generic Field that is both indexed and required.
referenceKey
text
"referencedContent"
The ID of a "reference" type field on the associated Content Type(s). If provided, that field in referenced content will be populated with references back to this content.
displayMode
text
"reference"
The displayMode to use when displaying referenced content.
placeholder
text
""
yes
Placeholder text when the input is empty.
allowBlur
boolean
false
Enable adding an unfinished item when the input loses focus.
minChars
number
1
The number of characters that must be typed before options are shown.
multiselect
Multiple text-entry widget provided by svelte-input-tags.
option
type
default
script
description
items
text
[]
yes
A list of possible values to be presented to content editors. Values should be text strings, but may use the "[value][:label]" format, e.g. "1:First Place". A script function may be used to retrieve options from an external API.
restrictToItems
boolean
false
yes
Only accept items from the provided items.
itemsFilter
boolean
true
yes
Turn this off to disable filtering the items. May be useful for some APIs.
placeholder
text
""
yes
Placeholder text when the input is empty.
onlyUnique
boolean
true
yes
Ensure that all entered items are unique.
allowBlur
boolean
false
Enable adding an unfinished item when the input loses focus.
minChars
number
1
The number of characters that must be typed before options are shown.
allowPaste
boolean
false
Enable pasting a tag or tag group.
allowDrop
boolean
false
Enable drag and drop of a tag or tag group.
splitWith
text
","
yes
The character that splits a group of items.
checkbox-text
Replaces the standard HTML checkbox input with a text-based input that should scale.
option
type
default
script
description
falseText
text
"☐"
yes
Character to show when the checkbox is not checked.
trueText
text
"☑︎"
yes
Character to show when the checkbox is not checked.
fontSize
number
150
yes
The relative size of the checkbox text, as a percentage.
labelBeforeCheckbox
boolean
false
yes
Render the text label before the checkbox element in HTML markup.