Assets
You can manage your project’s media and document files (“assets”) in Craft just like entries and other content types.
# Volumes
All of your assets live in “volumes”. Volumes are storage containers. A volume can be a directory on the web server, or a remote storage service like Amazon S3.
You can manage your project’s volumes from Settings → Assets.
All volumes let you choose whether the assets within them should have public URLs, and if so, what their base URL should be.
Volumes’ base URLs can be set to an environment variable, or begin with an alias. See Environmental Configuration to learn more about that.
# Local Volumes
Out of the box, you can create one type of volume, “Local”. Local volumes represent a directory on the local web server.
Local volumes have one setting: File System Path. Use this setting to define the path to the volume’s root directory on the server.
Local volumes’ file system path can be set to an environment variable, or begin with an alias. See Environmental Configuration to learn more about that.
Note that Craft/PHP must be able to write to the directory you created.
# Remote Volumes
If you would prefer to store your assets on a remote storage service like Amazon S3, you can install a plugin that provides the integration.
- Amazon S3 (opens new window) (first party)
- Google Cloud Storage (opens new window) (first party)
- Rackspace Cloud Files (opens new window) (first party)
- DigitalOcean Spaces (opens new window) (Værsågod)
- fortrabbit Object Storage (opens new window) (fortrabbit)
# Asset Custom Fields
Each of your volumes has a field layout, where you can set the fields that will be available to assets within that volume. You can edit a volume’s field layout by clicking the Field Layout tab when editing the volume.
Any fields you select here will be visible in the asset editor HUD that opens up when you double-click on an asset (either on the Assets page or from Assets fields).
# Assets Page
When you create your first volume, an Assets item will be added to the main control panel navigation. Clicking on it will take you to the Assets page, which shows a list of all of your volumes in the left sidebar, and the selected volume’s files in the main content area.
From this page, you can do the following:
- Upload new files
- Rename files
- Edit files’ titles and filenames
- Launch the Image Editor for a selected image
- Manage subfolders
- Move files to a different volume or subfolder (via drag and drop)
- Delete files
# Managing Subfolders
You can create a subfolder in one of your volumes by right-clicking the volume in the left sidebar, and choosing New subfolder.
Once you’ve created a subfolder, you can start dragging files into it.
You can create a nested subfolder within a subfolder by right-clicking the subfolder in the left sidebar, and again choosing New subfolder.
You can rename a subfolder by right-clicking on the subfolder in the left sidebar and choosing Rename folder.
You can delete a subfolder (and all assets within it) by right-clicking on the subfolder in the left sidebar and choosing Delete folder.
# Updating Asset Indexes
If any files are ever added, modified, or deleted outside of Craft (such as over FTP), you’ll need to tell Craft to update its indexes for the volume. You can do that from Utilities → Asset Indexes.
You will have the option to cache remote images. If you don’t have any remote volumes (Amazon S3, etc.), you can safely ignore it. Enabling the setting will cause the indexing process to take longer to complete, but it will improve the speed of image transform generation.
# Image Transforms
Craft provides a way to perform a variety of image transformations to your assets. See Image Transforms for more information.
# Image Editor
Craft provides a built-in Image Editor for making changes to your images. You can crop, straighten, rotate, and flip your images, as well as choose a focal point on them.
To launch the Image Editor, double-click an image (either on the Assets page or from an Assets field) and press Edit in the top-right of the image preview area in the HUD. Alternatively, you can select an asset on the Assets page and choose Edit image from the task menu (
# Focal Points
Set focal points on your images so Craft knows which part of the image to prioritize when determining how to crop your images for image transforms. Focal points take precedence over the transform’s Crop Position setting.
To set a focal point, open the Image Editor and click on the Focal Point button. A circular icon will appear in the center of your image. Drag it to wherever you want the image’s focal point to be.
To remove the focal point, click on the Focal Point button again.
Like other changes in the Image Editor, focal points won’t take effect until you’ve saved the image.
# Querying Assets
You can fetch assets in your templates or PHP code using asset queries.
Once you’ve created an asset query, you can set parameters on it to narrow down the results, and then execute it by calling .all()
. An array of Asset (opens new window) objects will be returned.
See Element Queries to learn about how element queries work.
# Example
We can display a list of thumbnails for images in a “Photos” volume by doing the following:
- Create an asset query with
craft.assets()
. - Set the volume and kind parameters on it.
- Fetch the assets with
.all()
. - Loop through the assets using a for (opens new window) tag to create the thumbnail list HTML.
{# Create an asset query with the 'volume' and 'kind' parameters #}
{% set myAssetQuery = craft.assets()
.volume('photos')
.kind('image') %}
{# Fetch the assets #}
{% set images = myAssetQuery.all() %}
{# Display the thumbnail list #}
<ul>
{% for image in images %}
<li><img src="{{ image.getUrl('thumb') }}" alt="{{ image.title }}"></li>
{% endfor %}
</ul>
When using asset.url
or asset.getUrl()
, the asset’s source volume must have “Assets in this volume have public URLs” enabled and a “Base URL” setting. Otherwise, the result will always be empty.
You can cache-bust asset URLs automatically by enabling the revAssetUrls config setting, or handle them individually by using Craft’s url()
function to append a query parameter with the last-modified timestamp:
<img src="{{ url(image.getUrl('thumb'), {v: image.dateModified.timestamp}) }}">
{# <img src="https://my-project.tld/images/_thumb/bar.jpg?v=1614374621"> #}
# Parameters
Asset queries support the following parameters:
Param | Description |
---|---|
addOrderBy | Adds additional ORDER BY columns to the query. |
afterPopulate | Performs any post-population processing on elements. |
andRelatedTo | Narrows the query results to only assets that are related to certain other elements. |
anyStatus | Removes element filters based on their statuses. |
asArray | Causes the query to return matching assets as arrays of data, rather than Asset (opens new window) objects. |
cache | Enables query cache for this Query. |
clearCachedResult | Clears the cached result (opens new window). |
dateCreated | Narrows the query results based on the assets’ creation dates. |
dateModified | Narrows the query results based on the assets’ files’ last-modified dates. |
dateUpdated | Narrows the query results based on the assets’ last-updated dates. |
fields | Returns the list of fields that should be returned by default by toArray() (opens new window) when no specific fields are specified. |
filename | Narrows the query results based on the assets’ filenames. |
fixedOrder | Causes the query results to be returned in the order specified by id. |
folderId | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. |
folderPath | Narrows the query results based on the folders the assets belong to, per the folders’ paths. |
height | Narrows the query results based on the assets’ image heights. |
id | Narrows the query results based on the assets’ IDs. |
ignorePlaceholders | Causes the query to return matching assets as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement() (opens new window). |
inReverse | Causes the query results to be returned in reverse order. |
includeSubfolders | Broadens the query results to include assets from any of the subfolders of the folder specified by folderId. |
kind | Narrows the query results based on the assets’ file kinds. |
limit | Determines the number of assets that should be returned. |
offset | Determines how many assets should be skipped in the results. |
orderBy | Determines the order that the assets should be returned in. (If empty, defaults to dateCreated DESC .) |
preferSites | If unique is set, this determines which site should be selected when querying multi-site elements. |
relatedTo | Narrows the query results to only assets that are related to certain other elements. |
search | Narrows the query results to only assets that match a search query. |
site | Determines which site(s) the assets should be queried in. |
siteId | Determines which site(s) the assets should be queried in, per the site’s ID. |
siteSettingsId | Narrows the query results based on the assets’ IDs in the elements_sites table. |
size | Narrows the query results based on the assets’ file sizes (in bytes). |
title | Narrows the query results based on the assets’ titles. |
trashed | Narrows the query results to only assets that have been soft-deleted. |
uid | Narrows the query results based on the assets’ UIDs. |
unique | Determines whether only elements with unique IDs should be returned by the query. |
uploader | Narrows the query results based on the user the assets were uploaded by, per the user’s IDs. |
volume | Narrows the query results based on the volume the assets belong to. |
volumeId | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. |
width | Narrows the query results based on the assets’ image widths. |
with | Causes the query to return matching assets eager-loaded with related elements. |
withTransforms | Causes the query to return matching assets eager-loaded with image transform indexes. |
# addOrderBy
Adds additional ORDER BY columns to the query.
# afterPopulate
Performs any post-population processing on elements.
# andRelatedTo
Narrows the query results to only assets that are related to certain other elements.
See Relations (opens new window) for a full explanation of how to work with this parameter.
{# Fetch all assets that are related to myCategoryA and myCategoryB #}
{% set assets = craft.assets()
.relatedTo(myCategoryA)
.andRelatedTo(myCategoryB)
.all() %}
# anyStatus
Removes element filters based on their statuses.
{# Fetch all assets, regardless of status #}
{% set assets = craft.assets()
.anyStatus()
.all() %}
# asArray
Causes the query to return matching assets as arrays of data, rather than Asset (opens new window) objects.
# cache
Enables query cache for this Query.
# clearCachedResult
Clears the cached result (opens new window).
# dateCreated
Narrows the query results based on the assets’ creation dates.
Possible values include:
Value | Fetches assets… |
---|---|
'>= 2018-04-01' | that were created on or after 2018-04-01. |
'< 2018-05-01' | that were created before 2018-05-01 |
['and', '>= 2018-04-04', '< 2018-05-01'] | that were created between 2018-04-01 and 2018-05-01. |
{# Fetch assets created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}
{% set assets = craft.assets()
.dateCreated(['and', ">= #{start}", "< #{end}"])
.all() %}
# dateModified
Narrows the query results based on the assets’ files’ last-modified dates.
Possible values include:
Value | Fetches assets… |
---|---|
'>= 2018-04-01' | that were modified on or after 2018-04-01. |
'< 2018-05-01' | that were modified before 2018-05-01 |
['and', '>= 2018-04-04', '< 2018-05-01'] | that were modified between 2018-04-01 and 2018-05-01. |
{# Fetch assets modified in the last month #}
{% set start = date('30 days ago')|atom %}
{% set assets = craft.assets()
.dateModified(">= #{start}")
.all() %}
# dateUpdated
Narrows the query results based on the assets’ last-updated dates.
Possible values include:
Value | Fetches assets… |
---|---|
'>= 2018-04-01' | that were updated on or after 2018-04-01. |
'< 2018-05-01' | that were updated before 2018-05-01 |
['and', '>= 2018-04-04', '< 2018-05-01'] | that were updated between 2018-04-01 and 2018-05-01. |
{# Fetch assets updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}
{% set assets = craft.assets()
.dateUpdated(">= #{lastWeek}")
.all() %}
# fields
Returns the list of fields that should be returned by default by toArray() (opens new window) when no specific fields are specified.
A field is a named element in the returned array by toArray() (opens new window). This method should return an array of field names or field definitions. If the former, the field name will be treated as an object property name whose value will be used as the field value. If the latter, the array key should be the field name while the array value should be the corresponding field definition which can be either an object property name or a PHP callable returning the corresponding field value. The signature of the callable should be:
function ($model, $field) {
// return field value
}
For example, the following code declares four fields:
email
: the field name is the same as the property nameemail
;firstName
andlastName
: the field names arefirstName
andlastName
, and their values are obtained from thefirst_name
andlast_name
properties;fullName
: the field name isfullName
. Its value is obtained by concatenatingfirst_name
andlast_name
.
return [
'email',
'firstName' => 'first_name',
'lastName' => 'last_name',
'fullName' => function ($model) {
return $model->first_name . ' ' . $model->last_name;
},
];
# filename
Narrows the query results based on the assets’ filenames.
Possible values include:
Value | Fetches assets… |
---|---|
'foo.jpg' | with a filename of foo.jpg . |
'foo*' | with a filename that begins with foo . |
'*.jpg' | with a filename that ends with .jpg . |
'*foo*' | with a filename that contains foo . |
'not *foo*' | with a filename that doesn’t contain foo . |
['*foo*', '*bar*'] | with a filename that contains foo or bar . |
['not', '*foo*', '*bar*'] | with a filename that doesn’t contain foo or bar . |
{# Fetch all the hi-res images #}
{% set assets = craft.assets()
.filename('*@2x*')
.all() %}
# fixedOrder
Causes the query results to be returned in the order specified by id.
If no IDs were passed to id, setting this to true
will result in an empty result set.
{# Fetch assets in a specific order #}
{% set assets = craft.assets()
.id([1, 2, 3, 4, 5])
.fixedOrder()
.all() %}
# folderId
Narrows the query results based on the folders the assets belong to, per the folders’ IDs.
Possible values include:
Value | Fetches assets… |
---|---|
1 | in a folder with an ID of 1. |
'not 1' | not in a folder with an ID of 1. |
[1, 2] | in a folder with an ID of 1 or 2. |
['not', 1, 2] | not in a folder with an ID of 1 or 2. |
{# Fetch assets in the folder with an ID of 1 #}
{% set assets = craft.assets()
.folderId(1)
.all() %}
This can be combined with includeSubfolders if you want to include assets in all the subfolders of a certain folder.
# folderPath
Narrows the query results based on the folders the assets belong to, per the folders’ paths.
Possible values include:
Value | Fetches assets… |
---|---|
foo/ | in a foo/ folder (excluding nested folders). |
foo/* | in a foo/ folder (including nested folders). |
'not foo/*' | not in a foo/ folder (including nested folders). |
['foo/*', 'bar/*'] | in a foo/ or bar/ folder (including nested folders). |
['not', 'foo/*', 'bar/*'] | not in a foo/ or bar/ folder (including nested folders). |
{# Fetch assets in the foo/ folder or its nested folders #}
{% set assets = craft.assets()
.folderPath('foo/*')
.all() %}
# height
Narrows the query results based on the assets’ image heights.
Possible values include:
Value | Fetches assets… |
---|---|
100 | with a height of 100. |
'>= 100' | with a height of at least 100. |
['>= 100', '<= 1000'] | with a height between 100 and 1,000. |
{# Fetch XL images #}
{% set assets = craft.assets()
.kind('image')
.height('>= 1000')
.all() %}
# id
Narrows the query results based on the assets’ IDs.
Possible values include:
Value | Fetches assets… |
---|---|
1 | with an ID of 1. |
'not 1' | not with an ID of 1. |
[1, 2] | with an ID of 1 or 2. |
['not', 1, 2] | not with an ID of 1 or 2. |
This can be combined with fixedOrder if you want the results to be returned in a specific order.
# ignorePlaceholders
Causes the query to return matching assets as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement() (opens new window).
# inReverse
Causes the query results to be returned in reverse order.
# includeSubfolders
Broadens the query results to include assets from any of the subfolders of the folder specified by folderId.
{# Fetch assets in the folder with an ID of 1 (including its subfolders) #}
{% set assets = craft.assets()
.folderId(1)
.includeSubfolders()
.all() %}
This will only work if folderId was set to a single folder ID.
# kind
Narrows the query results based on the assets’ file kinds.
Supported file kinds:
access
audio
compressed
excel
flash
html
illustrator
image
javascript
json
pdf
photoshop
php
powerpoint
text
video
word
xml
unknown
Possible values include:
Value | Fetches assets… |
---|---|
'image' | with a file kind of image . |
'not image' | not with a file kind of image .. |
['image', 'pdf'] | with a file kind of image or pdf . |
['not', 'image', 'pdf'] | not with a file kind of image or pdf . |
# limit
Determines the number of assets that should be returned.
# offset
Determines how many assets should be skipped in the results.
{# Fetch all assets except for the first 3 #}
{% set assets = craft.assets()
.offset(3)
.all() %}
# orderBy
Determines the order that the assets should be returned in. (If empty, defaults to dateCreated DESC
.)
{# Fetch all assets in order of date created #}
{% set assets = craft.assets()
.orderBy('dateCreated ASC')
.all() %}
# preferSites
If unique is set, this determines which site should be selected when querying multi-site elements.
For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C,
and this is set to ['c', 'b', 'a']
, then Foo will be returned for Site B, and Bar will be returned
for Site C.
If this isn’t set, then preference goes to the current site.
{# Fetch unique assets from Site A, or Site B if they don’t exist in Site A #}
{% set assets = craft.assets()
.site('*')
.unique()
.preferSites(['a', 'b'])
.all() %}
# relatedTo
Narrows the query results to only assets that are related to certain other elements.
See Relations (opens new window) for a full explanation of how to work with this parameter.
{# Fetch all assets that are related to myCategory #}
{% set assets = craft.assets()
.relatedTo(myCategory)
.all() %}
# search
Narrows the query results to only assets that match a search query.
See Searching (opens new window) for a full explanation of how to work with this parameter.
{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}
{# Fetch all assets that match the search query #}
{% set assets = craft.assets()
.search(searchQuery)
.all() %}
# site
Determines which site(s) the assets should be queried in.
The current site will be used by default.
Possible values include:
Value | Fetches assets… |
---|---|
'foo' | from the site with a handle of foo . |
['foo', 'bar'] | from a site with a handle of foo or bar . |
['not', 'foo', 'bar'] | not in a site with a handle of foo or bar . |
a craft\models\Site (opens new window) object | from the site represented by the object. |
'*' | from any site. |
If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use unique in conjunction with this.
# siteId
Determines which site(s) the assets should be queried in, per the site’s ID.
The current site will be used by default.
Possible values include:
Value | Fetches assets… |
---|---|
1 | from the site with an ID of 1 . |
[1, 2] | from a site with an ID of 1 or 2 . |
['not', 1, 2] | not in a site with an ID of 1 or 2 . |
'*' | from any site. |
{# Fetch assets from the site with an ID of 1 #}
{% set assets = craft.assets()
.siteId(1)
.all() %}
# siteSettingsId
Narrows the query results based on the assets’ IDs in the elements_sites
table.
Possible values include:
Value | Fetches assets… |
---|---|
1 | with an elements_sites ID of 1. |
'not 1' | not with an elements_sites ID of 1. |
[1, 2] | with an elements_sites ID of 1 or 2. |
['not', 1, 2] | not with an elements_sites ID of 1 or 2. |
{# Fetch the asset by its ID in the elements_sites table #}
{% set asset = craft.assets()
.siteSettingsId(1)
.one() %}
# size
Narrows the query results based on the assets’ file sizes (in bytes).
Possible values include:
Value | Fetches assets… |
---|---|
1000 | with a size of 1,000 bytes (1KB). |
'< 1000000' | with a size of less than 1,000,000 bytes (1MB). |
['>= 1000', '< 1000000'] | with a size between 1KB and 1MB. |
{# Fetch assets that are smaller than 1KB #}
{% set assets = craft.assets()
.size('< 1000')
.all() %}
# title
Narrows the query results based on the assets’ titles.
Possible values include:
Value | Fetches assets… |
---|---|
'Foo' | with a title of Foo . |
'Foo*' | with a title that begins with Foo . |
'*Foo' | with a title that ends with Foo . |
'*Foo*' | with a title that contains Foo . |
'not *Foo*' | with a title that doesn’t contain Foo . |
['*Foo*', '*Bar*'] | with a title that contains Foo or Bar . |
['not', '*Foo*', '*Bar*'] | with a title that doesn’t contain Foo or Bar . |
{# Fetch assets with a title that contains "Foo" #}
{% set assets = craft.assets()
.title('*Foo*')
.all() %}
# trashed
Narrows the query results to only assets that have been soft-deleted.
# uid
Narrows the query results based on the assets’ UIDs.
{# Fetch the asset by its UID #}
{% set asset = craft.assets()
.uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
.one() %}
# unique
Determines whether only elements with unique IDs should be returned by the query.
This should be used when querying elements from multiple sites at the same time, if “duplicate” results is not desired.
{# Fetch unique assets across all sites #}
{% set assets = craft.assets()
.site('*')
.unique()
.all() %}
# uploader
Narrows the query results based on the user the assets were uploaded by, per the user’s IDs.
Possible values include:
Value | Fetches assets… |
---|---|
1 | uploaded by the user with an ID of 1. |
a craft\elements\User (opens new window) object | uploaded by the user represented by the object. |
{# Fetch assets uploaded by the user with an ID of 1 #}
{% set assets = craft.assets()
.uploader(1)
.all() %}
# volume
Narrows the query results based on the volume the assets belong to.
Possible values include:
Value | Fetches assets… |
---|---|
'foo' | in a volume with a handle of foo . |
'not foo' | not in a volume with a handle of foo . |
['foo', 'bar'] | in a volume with a handle of foo or bar . |
['not', 'foo', 'bar'] | not in a volume with a handle of foo or bar . |
a volume (opens new window) object | in a volume represented by the object. |
{# Fetch assets in the Foo volume #}
{% set assets = craft.assets()
.volume('foo')
.all() %}
# volumeId
Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs.
Possible values include:
Value | Fetches assets… |
---|---|
1 | in a volume with an ID of 1. |
'not 1' | not in a volume with an ID of 1. |
[1, 2] | in a volume with an ID of 1 or 2. |
['not', 1, 2] | not in a volume with an ID of 1 or 2. |
':empty:' | that haven’t been stored in a volume yet |
{# Fetch assets in the volume with an ID of 1 #}
{% set assets = craft.assets()
.volumeId(1)
.all() %}
# width
Narrows the query results based on the assets’ image widths.
Possible values include:
Value | Fetches assets… |
---|---|
100 | with a width of 100. |
'>= 100' | with a width of at least 100. |
['>= 100', '<= 1000'] | with a width between 100 and 1,000. |
{# Fetch XL images #}
{% set assets = craft.assets()
.kind('image')
.width('>= 1000')
.all() %}
# with
Causes the query to return matching assets eager-loaded with related elements.
See Eager-Loading Elements (opens new window) for a full explanation of how to work with this parameter.
{# Fetch assets eager-loaded with the "Related" field’s relations #}
{% set assets = craft.assets()
.with(['related'])
.all() %}
# withTransforms
Causes the query to return matching assets eager-loaded with image transform indexes.
This can improve performance when displaying several image transforms at once, if the transforms have already been generated.
Transforms can be specified as their handle or an object that contains width
and/or height
properties.
You can include srcset
-style sizes (e.g. 100w
or 2x
) following a normal transform definition, for example:
When a srcset
-style size is encountered, the preceding normal transform definition will be used as a
reference when determining the resulting transform dimensions.