androidx.compose.ui.text.font

Interfaces

AndroidFont.TypefaceLoader

Loader for loading an AndroidFont and producing an android.graphics.Typeface.

android
Font

The interface of the font resource.

Cmn
Font.ResourceLoader

This interface is deprecated. Replaced with FontFamily.Resolver during the introduction of async fonts, all usages should be replaced.

Cmn
FontFamily.Resolver

Main interface for resolving FontFamily into a platform-specific typeface for use in Compose-based applications.

Cmn
FontVariation.Setting

Represents a single point in a variation, such as 0.7 or 100

Cmn
Typeface

A class that can be used for changing the font used in text.

Cmn

Classes

AndroidFont

Font for use on Android.

android
DeviceFontFamilyName

An Android system installed font family name as used by Typeface.create.

android
FileBasedFontFamily

A base class of FontFamilys that is created from file sources.

Cmn
FontFamily

The primary typography interface for Compose applications.

Cmn
FontListFontFamily

Defines a font family with list of Font.

Cmn
FontLoadingStrategy

Font loading strategy for a Font in a FontListFontFamily.

Cmn
FontStyle

Defines whether the font is Italic or Normal.

Cmn
FontSynthesis

Possible options for font synthesis.

Cmn
FontVariation.Settings

A collection of settings to apply to a single font.

Cmn
FontWeight

The thickness of the glyphs, in a range of 1, 1000.

Cmn
GenericFontFamily

Defines a font family with a generic font family name.

Cmn
LoadedFontFamily

Defines a font family that is already loaded Typeface.

Cmn
ResourceFont

Defines a font to be used while rendering text with resource ID.

Cmn
SystemFontFamily

A base class of FontFamilys installed on the system.

Cmn

Objects

FontVariation

Set font variation settings.

Cmn

Top-level functions summary

Font
Font(
    familyName: DeviceFontFamilyName,
    weight: FontWeight,
    style: FontStyle,
    variationSettings: FontVariation.Settings
)

Describes a system-installed font that may be present on some Android devices.

android
Font
@RequiresApi(value = 26)
Font(
    fileDescriptor: ParcelFileDescriptor,
    weight: FontWeight,
    style: FontStyle,
    variationSettings: FontVariation.Settings
)

Create a Font declaration from a ParcelFileDescriptor.

android
Font
Font(
    file: File,
    weight: FontWeight,
    style: FontStyle,
    variationSettings: FontVariation.Settings
)

Create a Font declaration from a file.

android
Font
Font(
    resId: Int,
    weight: FontWeight,
    style: FontStyle,
    loadingStrategy: FontLoadingStrategy
)

Creates a Font with using resource ID.

Cmn
Font
Font(
    path: String,
    assetManager: AssetManager,
    weight: FontWeight,
    style: FontStyle,
    variationSettings: FontVariation.Settings
)

Create a Font declaration from a file in the assets directory.

android
Font
@ExperimentalTextApi
Font(
    resId: Int,
    weight: FontWeight,
    style: FontStyle,
    loadingStrategy: FontLoadingStrategy,
    variationSettings: FontVariation.Settings
)
Cmn
FontFamily
FontFamily(vararg fonts: Font)

Construct a font family that contains list of custom font files.

Cmn
FontFamily
FontFamily(fonts: List<Font>)

Construct a font family that contains list of custom font files.

Cmn
FontFamily
FontFamily(typeface: Typeface)

Creates a FontFamily from Android Typeface.

android
FontFamily
FontFamily(typeface: Typeface)

Construct a font family that contains loaded font family: Typeface.

Cmn
Typeface
Typeface(typeface: Typeface)

Returns a Compose androidx.compose.ui.text.font.Typeface from Android Typeface.

android
Typeface
Typeface(
    context: Context,
    fontFamily: FontFamily,
    styles: List<Pair<FontWeightFontStyle>>?
)

This function is deprecated. This API is deprecated with the introduction of async fonts which cannot resolve in this context.

android
FontFamily.Resolver

Create a new fontFamilyResolver for use outside of composition context

android
FontFamily.Resolver

Create a new fontFamilyResolver for use outside of composition context

android
FontFamily.Resolver

Create a new fontFamilyResolver for use outside of composition context with a coroutine context.

android
FontFamily.Resolver
createFontFamilyResolver(
    context: Context,
    coroutineContext: CoroutineContext
)

Create a new fontFamilyResolver for use outside of composition context with a coroutine context.

android
FontFamily.Resolver
createFontFamilyResolver(
    fontResourceLoader: Font.ResourceLoader,
    context: Context
)

This function is deprecated. This exists to bridge existing Font.ResourceLoader subclasses to be used as aFontFamily.ResourceLoader during upgrade.

android
FontWeight
lerp(start: FontWeight, stop: FontWeight, fraction: Float)

Linearly interpolate between two font weights.

Cmn

Extension functions summary

State<Typeface>
FontFamily.Resolver.resolveAsTypeface(
    fontFamily: FontFamily?,
    fontWeight: FontWeight,
    fontStyle: FontStyle,
    fontSynthesis: FontSynthesis
)

Resolve a font to an Android Typeface

android
FontFamily

Create a FontFamily from this single Font.

Cmn

Top-level functions

Font

fun Font(
    familyName: DeviceFontFamilyName,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal,
    variationSettings: FontVariation.Settings = FontVariation.Settings()
): Font

Describes a system-installed font that may be present on some Android devices.

You should assume this will not resolve on some devices and provide an appropriate fallback font.

Family name lookup is device and platform-specific, and different OEMs may install different fonts. All fonts described this way are considered FontLoadingStrategy.OptionalLocal and will continue to the next font in the chain if they are not present on a device.

Use this method to prefer locally pre-loaded system fonts when they are available. System fonts are always more efficient to load than reading a font file, or downloadable fonts.

A system installed font resolution will never trigger text reflow.

This descriptor will trust the weight and style parameters as accurate. However, it is not required that the loaded fonts actually support the requested weight and style and this may trigger platform level font-synthesis of fake bold or fake italic during font resolution.

This Font can not describe the system-installed Typeface.DEFAULT. All other system-installed fonts are allowed.

Note: When setting variationSettings any unset axis may be reset to the font default, ignoring any axis restrictions in fonts.xml or font_customizations.xml. This may have surprising side-effects when named fonts differ only by the default axis settings in XML. When setting variation axis for device fonts, ensure you set all possible settings for the font.

Parameters
familyName: DeviceFontFamilyName

Android system-installed font family name

weight: FontWeight = FontWeight.Normal

weight to load

style: FontStyle = FontStyle.Normal

style to load

variationSettings: FontVariation.Settings = FontVariation.Settings()

font variation settings, unset by default to load default VF from system

Throws
kotlin.IllegalArgumentException

if familyName is empty

Font

@RequiresApi(value = 26)
fun Font(
    fileDescriptor: ParcelFileDescriptor,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal,
    variationSettings: FontVariation.Settings = FontVariation.Settings(weight, style)
): Font

Create a Font declaration from a ParcelFileDescriptor. The content of the ParcelFileDescriptor is read during construction.

Parameters
fileDescriptor: ParcelFileDescriptor

the file descriptor for the font file.

weight: FontWeight = FontWeight.Normal

The weight of the font. The system uses this to match a font to a font request that is given in a androidx.compose.ui.text.SpanStyle.

style: FontStyle = FontStyle.Normal

The style of the font, normal or italic. The system uses this to match a font to a font request that is given in a androidx.compose.ui.text.SpanStyle.

variationSettings: FontVariation.Settings = FontVariation.Settings(weight, style)

these settings are applied to a variable font when the font is loaded

Font

fun Font(
    file: File,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal,
    variationSettings: FontVariation.Settings = FontVariation.Settings(weight, style)
): Font

Create a Font declaration from a file. The content of the File is read during construction.

Parameters
file: File

the font file.

weight: FontWeight = FontWeight.Normal

The weight of the font. The system uses this to match a font to a font request that is given in a androidx.compose.ui.text.SpanStyle.

style: FontStyle = FontStyle.Normal

The style of the font, normal or italic. The system uses this to match a font to a font request that is given in a androidx.compose.ui.text.SpanStyle.

variationSettings: FontVariation.Settings = FontVariation.Settings(weight, style)

on API 26 and above these settings are applied to a variable font when the font is loaded

fun Font(
    resId: Int,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal,
    loadingStrategy: FontLoadingStrategy = FontLoadingStrategy.Blocking
): Font

Creates a Font with using resource ID.

Allows control over FontLoadingStrategy strategy. You may supply FontLoadingStrategy.Blocking, or FontLoadingStrategy.OptionalLocal for fonts that are expected on the first frame.

FontLoadingStrategy.Async, will load the font in the background and cause text reflow when loading completes. Fonts loaded from a remote source via resources should use FontLoadingStrategy.Async.

Parameters
resId: Int

The resource ID of the font file in font resources. i.e. "R.font.myfont".

weight: FontWeight = FontWeight.Normal

The weight of the font. The system uses this to match a font to a font request that is given in a androidx.compose.ui.text.SpanStyle.

style: FontStyle = FontStyle.Normal

The style of the font, normal or italic. The system uses this to match a font to a font request that is given in a androidx.compose.ui.text.SpanStyle.

loadingStrategy: FontLoadingStrategy = FontLoadingStrategy.Blocking

Load strategy for this font, may be async for async resource fonts

See also
FontFamily

Font

fun Font(
    path: String,
    assetManager: AssetManager,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal,
    variationSettings: FontVariation.Settings = FontVariation.Settings(weight, style)
): Font

Create a Font declaration from a file in the assets directory. The content of the File is read during construction.

Parameters
path: String

full path starting from the assets directory (i.e. dir/myfont.ttf for assets/dir/myfont.ttf).

assetManager: AssetManager

Android AssetManager

weight: FontWeight = FontWeight.Normal

The weight of the font. The system uses this to match a font to a font request that is given in a androidx.compose.ui.text.SpanStyle.

style: FontStyle = FontStyle.Normal

The style of the font, normal or italic. The system uses this to match a font to a font request that is given in a androidx.compose.ui.text.SpanStyle.

variationSettings: FontVariation.Settings = FontVariation.Settings(weight, style)

on API 26 and above these settings are applied to a variable font when the font is loaded

@ExperimentalTextApi
fun Font(
    resId: Int,
    weight: FontWeight = FontWeight.Normal,
    style: FontStyle = FontStyle.Normal,
    loadingStrategy: FontLoadingStrategy = FontLoadingStrategy.Blocking,
    variationSettings: FontVariation.Settings = FontVariation.Settings(weight, style)
): Font

FontFamily

fun FontFamily(vararg fonts: Font): FontFamily

Construct a font family that contains list of custom font files.

Parameters
vararg fonts: Font

list of font files

FontFamily

fun FontFamily(fonts: List<Font>): FontFamily

Construct a font family that contains list of custom font files.

Parameters
fonts: List<Font>

list of font files

FontFamily

fun FontFamily(typeface: Typeface): FontFamily

Creates a FontFamily from Android Typeface.

Parameters
typeface: Typeface

Android Typeface instance

FontFamily

fun FontFamily(typeface: Typeface): FontFamily

Construct a font family that contains loaded font family: Typeface.

Parameters
typeface: Typeface

A typeface instance.

Typeface

fun Typeface(typeface: Typeface): Typeface

Returns a Compose androidx.compose.ui.text.font.Typeface from Android Typeface.

Parameters
typeface: Typeface

Android Typeface instance

Typeface

fun Typeface(
    context: Context,
    fontFamily: FontFamily,
    styles: List<Pair<FontWeightFontStyle>>? = null
): Typeface

Build an Android specific Typeface from FontFamily.

You can pass styles for loading only specific styles.

This function caches the internal native Typeface but always create the new Typeface object. Caller should cache if necessary.

Parameters
context: Context

the context to be used for loading Typeface.

fontFamily: FontFamily

the font family to be loaded

styles: List<Pair<FontWeightFontStyle>>? = null

optional style filter for loading subset of fontFamily. null means load all fonts in fontFamily.

createFontFamilyResolver

fun createFontFamilyResolver(): FontFamily.Resolver

Create a new fontFamilyResolver for use outside of composition context

Example usages:

  • Before starting compose to preload fonts

  • Creating Paragraph objects on background thread

Usages inside of Composition should use LocalFontFamilyResolver.current

createFontFamilyResolver

fun createFontFamilyResolver(context: Context): FontFamily.Resolver

Create a new fontFamilyResolver for use outside of composition context

Example usages:

  • Application.onCreate to preload fonts

  • Creating Paragraph objects on background thread

Usages inside of Composition should use LocalFontFamilyResolver.current

All instances of FontFamily.Resolver created by createFontFamilyResolver share the same typeface caches.

createFontFamilyResolver

@ExperimentalTextApi
fun createFontFamilyResolver(coroutineContext: CoroutineContext): FontFamily.Resolver

Create a new fontFamilyResolver for use outside of composition context with a coroutine context.

Example usages:

  • Before starting compose to preload fonts

  • Creating Paragraph objects on background thread

  • Configuring LocalFontFamilyResolver with a different CoroutineScope

Usages inside of Composition should use LocalFontFamilyResolver.current

Any kotlinx.coroutines.CoroutineExceptionHandler provided will be called with exceptions related to fallback font loading. These exceptions are not fatal, and indicate that font fallback continued to the next font load.

If no kotlinx.coroutines.CoroutineExceptionHandler is provided, a default implementation will be added that ignores all exceptions.

Parameters
coroutineContext: CoroutineContext

context to launch async requests in during resolution.

createFontFamilyResolver

fun createFontFamilyResolver(
    context: Context,
    coroutineContext: CoroutineContext
): FontFamily.Resolver

Create a new fontFamilyResolver for use outside of composition context with a coroutine context.

Example usages:

  • Application.onCreate to preload fonts

  • Creating Paragraph objects on background thread

  • Configuring LocalFontFamilyResolver with a different CoroutineScope

Usages inside of Composition should use LocalFontFamilyResolver.current

Any kotlinx.coroutines.CoroutineExceptionHandler provided will be called with exceptions related to fallback font loading. These exceptions are not fatal, and indicate that font fallback continued to the next font load.

If no kotlinx.coroutines.CoroutineExceptionHandler is provided, a default implementation will be added that ignores all exceptions.

All instances of FontFamily.Resolver created by createFontFamilyResolver share the same typeface caches.

Parameters
context: Context

Android context for resolving fonts

coroutineContext: CoroutineContext

context to launch async requests in during resolution.

createFontFamilyResolver

fun createFontFamilyResolver(
    fontResourceLoader: Font.ResourceLoader,
    context: Context
): FontFamily.Resolver

Bridge between subclasses of Font.ResourceLoader and the new FontFamily.Resolver API.

To use add as a CompositionLocal replacing the default FontFamily.Resolver:

LocalFontFamilyResolver provides createFontFamilyResolver(myFontResourceLoader, context)

This FontFamily.Resolver is capable of loading all fonts that the default FontFamily.Resolver is. In addition, it will delegate all resource fonts to the provided Font.ResourceLoader, preserving the behavior of Compose 1.0.

This method will be removed by Compose 2.0, and callers should migrate to using AndroidFont to implement the same behavior using font fallback chains.

A FontFamily.Resolver created this way will not share caches with other FontFamily.Resolvers.

lerp

fun lerp(start: FontWeight, stop: FontWeight, fraction: Float): FontWeight

Linearly interpolate between two font weights.

The fraction argument represents position on the timeline, with 0.0 meaning that the interpolation has not started, returning start (or something equivalent to start), 1.0 meaning that the interpolation has finished, returning stop (or something equivalent to stop), and values in between meaning that the interpolation is at the relevant point on the timeline between start and stop. The interpolation can be extrapolated beyond 0.0 and 1.0, so negative values and values greater than 1.0 are valid (and can easily be generated by curves).

Values for fraction are usually obtained from an Animation, such as an AnimationController.

Extension functions

resolveAsTypeface

fun FontFamily.Resolver.resolveAsTypeface(
    fontFamily: FontFamily? = null,
    fontWeight: FontWeight = FontWeight.Normal,
    fontStyle: FontStyle = FontStyle.Normal,
    fontSynthesis: FontSynthesis = FontSynthesis.All
): State<Typeface>

Resolve a font to an Android Typeface

On Android, font resolution always produces an android.graphics.Typeface.

This convenience method converts State to State to avoid casting the result.

Parameters
fontFamily: FontFamily? = null

fontFamily to resolve from

fontWeight: FontWeight = FontWeight.Normal

font weight to resolve in fontFamily, will use closest match if not exact

fontStyle: FontStyle = FontStyle.Normal

italic or upright text, to resolve in fontFamily

fontSynthesis: FontSynthesis = FontSynthesis.All

allow font synthesis if fontFamily or fontStyle don't have an exact match. This will allow "fake bold" (drawing with too wide a brush) and "fake italic" (drawing then skewing) to be applied when no exact match is present for the weight and style.

toFontFamily

fun Font.toFontFamily(): FontFamily

Create a FontFamily from this single Font.